linespec build

.linespec

create_todo_success.linespec

TEST <name>        (optional)
VARS               (optional — declare typed variables)
RECEIVE
EXPECT (0..n)
EXPECT_NOT (0..n)
RESPOND

TEST <test_name>

VARS
  VAR_NAME: <type> [constraint=value ...]
  VAR_NAME: <type> [constraint=value ...]
  ...

TEST get_user_with_vars

VARS
  AUTH_TOKEN: string length=32 charset=alphanumeric
  USER_ID: integer min=1 max=9999

RECEIVE HTTP:GET /api/v1/users/${USER_ID}
HEADERS
  Authorization: Bearer ${AUTH_TOKEN}

EXPECT READ:MYSQL users
USING_SQL """
SELECT users.* FROM `users` WHERE `users`.`token` = '${AUTH_TOKEN}' LIMIT 1
"""
RETURNS {{payloads/user_response.json}}

EXPECT READ:MYSQL users
USING_SQL_CONTAINS """
WHERE users.id =
"""
RETURNS {{payloads/user_response.json}}

RESPOND HTTP:200
WITH {{payloads/user_public_response.json}}

VARS
  AUTH_TOKEN: string pattern=prov-[0-9]{4}-[a-f0-9]{8}

VARS
  ORDER_STATUS: enum values=pending,active,cancelled

RECEIVE HTTP:<METHOD> <URL>
[WITH {{<body_file>}}]
[HEADERS
  <header_name>: <header_value>
  ...]

RECEIVE HTTP:POST /api/v1/todos
WITH {{todo.yaml}}

RECEIVE HTTP:GET /api/v1/users/42
HEADERS
  Authorization: Bearer token_abc123xyz

RECEIVE KAFKA:<topic_name>
WITH {{<payload_file>}}
[TIMEOUT <duration>]

RECEIVE KAFKA:order-events
WITH {{payloads/order_created.yaml}}
TIMEOUT 30s

RECEIVE JOB
WITH {{<payload_file>}}
[TIMEOUT <duration>]

RECEIVE JOB
WITH {{<payload_file>}}
[TIMEOUT <duration>]

RECEIVE JOB
TIMEOUT <duration>

job_backend:
  type: redis       # redis | kafka | scheduled
  queue: worker:jobs  # Redis queue key or Kafka topic (omit for scheduled)

# Redis-backed worker (e.g. Asynq, Sidekiq, RQ, Dramatiq)
RECEIVE JOB
WITH {{payloads/email_job.json}}

EXPECT READ:POSTGRESQL
ACCESSING_TABLES [users]
VERIFY_OPERATION SELECT
RETURNS {{payloads/user_row.yaml}}

EXPECT HTTP:POST /api/send
RETURNS {{payloads/email_sent.json}}

EXPECT WRITE:POSTGRESQL
ACCESSING_TABLES [email_log]
VERIFY_OPERATION INSERT

# Scheduled/cron job (observe-only, no seed)
RECEIVE JOB
TIMEOUT 30s

EXPECT HTTP:GET /api/users
RETURNS {{payloads/users_list.json}}

EXPECT WRITE:POSTGRESQL
ACCESSING_TABLES [users]
VERIFY_OPERATION INSERT

EXPECT <CHANNEL> <resource>
[USING_SQL """
<raw-sql-query>
"""]
[USING_SQL_CONTAINS """
<sql-fragment>
"""]
[WITH {{<request_file>}}]
[RETURNS {{<response_file>}}]
[RETURNS EMPTY]
[VERIFY query CONTAINS '<string>']
[VERIFY query NOT_CONTAINS '<string>']
[VERIFY query MATCHES /<regex>/]

EXPECT READ:MYSQL
ACCESSING_TABLES [users]
...

# Route by table only — one mock per table, no further verification needed
EXPECT READ:MYSQL
ACCESSING_TABLES [users]
VERIFY_OPERATION SELECT
RETURNS {{user.yaml}}

# Verify a specific WHERE value — stable even if ORM adds ORDER BY or LIMIT
EXPECT READ:MYSQL
ACCESSING_TABLES [users]
VERIFY_WHERE
  id: 42
RETURNS {{user.yaml}}

# Verify WHERE column presence without caring about the value (e.g. auth token)
EXPECT READ:MYSQL
ACCESSING_TABLES [users]
VERIFY_WHERE
  token: PRESENT
RETURNS {{user.yaml}}

# Verify columns in the WHERE clause — for multi-column conditions
EXPECT READ:MYSQL
ACCESSING_TABLES [todos]
VERIFY_OPERATION SELECT
VERIFY_WHERE_COLUMNS [id, user_id]
RETURNS {{todo.yaml}}

# Verify written values for INSERT
EXPECT WRITE:MYSQL
ACCESSING_TABLES [users]
VERIFY_OPERATION INSERT
VERIFY_WRITTEN_VALUES
  email: john@example.com
  name: John Doe
WITH {{user_write.yaml}}

# CALL N — disambiguate multiple identical queries by ordering
EXPECT READ:MYSQL CALL 1
ACCESSING_TABLES [users]
VERIFY_OPERATION SELECT
RETURNS {{user.yaml}}

EXPECT READ:MYSQL CALL 2
ACCESSING_TABLES [users]
VERIFY_OPERATION SELECT
RETURNS EMPTY

# JOIN: two tables in ACCESSING_TABLES — matches queries that touch both
EXPECT READ:POSTGRESQL
ACCESSING_TABLES [orders, users]
VERIFY_OPERATION SELECT
VERIFY_WHERE_COLUMNS [user_id]
RETURNS {{orders_with_user.yaml}}

# Exact match — fragile against ORM column-order or LIMIT changes
EXPECT READ:MYSQL users
USING_SQL """
SELECT * FROM users WHERE id = 42 LIMIT 1
"""
RETURNS {{user.yaml}}

# Substring match — still fragile against parameter binding style ($1 vs ?)
EXPECT READ:MYSQL users
USING_SQL_CONTAINS """
WHERE users.id = 42
"""
RETURNS {{user.yaml}}

EXPECT HTTP:<METHOD> <URL>
[HEADERS
  <header_name>: <header_value>
  ...]
[WITH {{<request_body>}}]
RETURNS {{<response_body>}}
[RESPONSE_HEADERS
  <header_name>: <header_value>
  ...]

EXPECT HTTP:POST http://payment-service.local/charge
HEADERS
  Idempotency-Key: ${KEY}        # matched against the actual request headers
WITH {{payloads/charge_request.json}}   # the request body must match this
RETURNS {{payloads/charge_response.json}}   # mocked response body
RESPONSE_HEADERS
  Content-Type: application/json

EXPECT HTTP:GET http://user-service.local/users/42
HEADERS
  Authorization: Bearer token_abc123xyz
RETURNS {{user_info.yaml}}

# Simulate a network/connection failure (TCP close, no response)
EXPECT HTTP:GET http://user-service.local/users/42
RETURNS ERROR

# Simulate a specific error condition (label is for readability)
EXPECT HTTP:POST http://temporal.local/workflows
RETURNS ERROR cycle_detected

# Return a non-200 HTTP status (no body)
EXPECT HTTP:POST http://payment-service.local/charge
RETURNS HTTP:429

# Non-200 status WITH a response body: put a `status` field in the RETURNS payload
EXPECT HTTP:GET http://auth-service.local/validate
RETURNS {{payloads/auth_error.json}}   # auth_error.json contains `status: 401` plus the body

EXPECT READ:MYSQL [<table_name>] [CALL N]
[ACCESSING_TABLES [<table1>, <table2>, ...]]
[VERIFY_OPERATION SELECT]
[VERIFY_WHERE_COLUMNS [<col1>, <col2>, ...]]
[VERIFY_WHERE
  <col>: <value>
  ...]
RETURNS {{<response_file>}}

EXPECT READ:MYSQL <table_name>
[USING_SQL """
<SQL SELECT statement>
"""]
[USING_SQL_CONTAINS """
<sql-fragment>
"""]
RETURNS {{<response_file>}}

EXPECT READ:MYSQL
ACCESSING_TABLES [users]
VERIFY_WHERE
  id: 42
RETURNS {{user_response.yaml}}

EXPECT READ:MYSQL
ACCESSING_TABLES [todos]
VERIFY_OPERATION SELECT
VERIFY_WHERE_COLUMNS [id, user_id]
RETURNS {{todo.yaml}}

EXPECT READ:MYSQL
ACCESSING_TABLES [users]
VERIFY_OPERATION SELECT
RETURNS EMPTY

EXPECT WRITE:MYSQL [<table_name>] [CALL N]
[ACCESSING_TABLES [<table1>, <table2>, ...]]
[VERIFY_OPERATION INSERT|UPDATE|DELETE]
[VERIFY_WRITTEN_VALUES
  <col>: <value>
  ...]
[WITH {{<input_payload>}}]
[RETURNS {{<write_result_file>}}]
[VERIFY query CONTAINS '<string>']
[VERIFY query NOT_CONTAINS '<string>']
[VERIFY query MATCHES /<regex>/]

EXPECT WRITE:MYSQL <table_name>
[USING_SQL """
<SQL INSERT/UPDATE/DELETE statement>
"""]
[USING_SQL_CONTAINS """
<sql-fragment>
"""]
[WITH {{<input_payload>}}]
[RETURNS {{<write_result_file>}}]
[VERIFY query CONTAINS '<string>']
[VERIFY query NOT_CONTAINS '<string>']
[VERIFY query MATCHES /<regex>/]

EXPECT WRITE:MYSQL
ACCESSING_TABLES [users]
VERIFY_OPERATION INSERT
VERIFY_WRITTEN_VALUES
  email: john@example.com
  name: John Doe
WITH {{user_create.yaml}}
VERIFY query MATCHES /\bpassword_digest\b/

EXPECT WRITE:MYSQL CALL 1
ACCESSING_TABLES [orders]
VERIFY_OPERATION INSERT
WITH {{order_insert.yaml}}
RETURNS {{order_insert_result.yaml}}

EXPECT WRITE:MYSQL CALL 2
ACCESSING_TABLES [orders]
VERIFY_OPERATION UPDATE
WITH {{order_status_update.yaml}}
RETURNS {{order_update_result.yaml}}

affected_rows: 1
last_insert_id: 42

affected_rows: 1

EXPECT READ:POSTGRESQL [<table_name>] [CALL N]
[ACCESSING_TABLES [<table1>, <table2>, ...]]
[VERIFY_OPERATION SELECT]
[VERIFY_WHERE_COLUMNS [<col1>, <col2>, ...]]
[VERIFY_WHERE
  <col>: <value>
  ...]
RETURNS {{<response_file>}}

EXPECT READ:POSTGRESQL
ACCESSING_TABLES [notifications]
VERIFY_OPERATION SELECT
VERIFY_WHERE_COLUMNS [recipient]
RETURNS {{notifications.yaml}}

EXPECT READ:POSTGRESQL <table_name>
[USING_SQL """
<SQL SELECT statement>
"""]
[USING_SQL_CONTAINS """
<sql-fragment>
"""]
RETURNS {{<response_file>}}

EXPECT WRITE:POSTGRESQL [<table_name>] [CALL N]
[ACCESSING_TABLES [<table1>, <table2>, ...]]
[VERIFY_OPERATION INSERT|UPDATE|DELETE]
[VERIFY_WRITTEN_VALUES
  <col>: <value>
  ...]
[WITH {{<input_payload>}}]
[RETURNS {{<write_result_file>}}]
[VERIFY query CONTAINS '<string>']
[VERIFY query NOT_CONTAINS '<string>']
[VERIFY query MATCHES /<regex>/]

EXPECT WRITE:POSTGRESQL <table_name>
[USING_SQL """
<SQL INSERT/UPDATE/DELETE statement>
"""]
[USING_SQL_CONTAINS """
<sql-fragment>
"""]
[WITH {{<input_payload>}}]
[RETURNS {{<write_result_file>}}]
[VERIFY query CONTAINS '<string>']
[VERIFY query NOT_CONTAINS '<string>']
[VERIFY query MATCHES /<regex>/]

# write_result.yaml
affected_rows: 3

EXPECT READ:REDIS <COMMAND> <key>
RETURNS {{<response_file>}}

EXPECT READ:REDIS <COMMAND> <key>
RETURNS EMPTY

EXPECT READ:REDIS GET auth:cache:${AUTH_TOKEN}
RETURNS {{payloads/cached_user.json}}

EXPECT READ:REDIS GET session:${SESSION_ID}
RETURNS EMPTY

EXPECT WRITE:REDIS <COMMAND> <key>
[WITH {{<input_payload>}}]
[VERIFY command CONTAINS '<string>']
[VERIFY command NOT_CONTAINS '<string>']
[VERIFY command MATCHES /<regex>/]
[VERIFY key CONTAINS '<string>']
[VERIFY key NOT_CONTAINS '<string>']
[VERIFY key MATCHES /<regex>/]
[VERIFY value CONTAINS '<string>']
[VERIFY value NOT_CONTAINS '<string>']
[VERIFY value MATCHES /<regex>/]

EXPECT WRITE:REDIS SET session:abc
WITH {{payloads/session-data.json}}

EXPECT WRITE:REDIS DEL user:123
VERIFY command CONTAINS 'DEL'
VERIFY key CONTAINS 'user:'

EXPECT READ:MONGODB <collection>
RETURNS {{<response_file>}}

EXPECT READ:MONGODB <collection>
RETURNS EMPTY

EXPECT READ:MONGODB products
RETURNS {{payloads/products_list.json}}

EXPECT READ:MONGODB users
RETURNS EMPTY

EXPECT WRITE:MONGODB <collection>
[WITH {{<input_payload>}}]

EXPECT WRITE:MONGODB products
WITH {{payloads/create_product_request.json}}

EXPECT GRPC:<ServiceName>/<MethodName>
[WITH {{<request_payload>}}]
RETURNS {{<response_payload>}} | EMPTY

infrastructure:
  grpc: true

dependencies:
- name: user-grpc-service
  type: grpc
  host: user-grpc-service.local
  port: 50051

EXPECT GRPC:users.UserService/GetUser
WITH {{payloads/get_user_grpc_request.yaml}}
RETURNS {{payloads/get_user_grpc_response.json}}

# Service-level default — applies to all gRPC dependencies
grpc_descriptor_set: proto/workflow.pb

dependencies:
- name: workflow-service
  type: grpc
  host: temporal
  port: 7233

# Per-dependency override — takes precedence over the service-level default
- name: user-grpc-service
  type: grpc
  host: user-grpc-service.local
  port: 50051
  grpc_descriptor_set: proto/user.pb

protoc --include_imports --descriptor_set_out=workflow.proto workflow.proto

EXPECT <CHANNEL> <resource>
[USING_SQL """<SQL>"""]
[WITH {{<input_payload>}}]
VERIFY query CONTAINS '<string>'
VERIFY query NOT_CONTAINS '<string>'
VERIFY query MATCHES /<regex>/

EXPECT WRITE:REDIS <COMMAND> <key>
VERIFY command CONTAINS '<string>'
VERIFY key CONTAINS '<string>'
VERIFY value CONTAINS '<string>'

# GOOD: Uses word boundaries to match exact column name
VERIFY query MATCHES /\bpassword_digest\b/

# BAD: Would also match 'password_digest' in 'old_password_digest_column'
VERIFY query CONTAINS 'password_digest'

# GOOD: Checks for exact column reference
VERIFY query NOT_CONTAINS '`password`'

# BAD: Would fail on 'password_digest' because it contains 'password'
VERIFY query NOT_CONTAINS 'password'

TEST create-user-with-hashing
RECEIVE HTTP:POST /api/v1/users
WITH {{user_create_request.yaml}}

# Ensure password is hashed before storage
EXPECT WRITE:MYSQL users
WITH {{user_with_hashed_password.yaml}}
VERIFY query MATCHES /\bpassword_digest\b/
VERIFY query NOT_CONTAINS '`password`'

RESPOND HTTP:201

TEST delete-user-clears-cache
RECEIVE HTTP:DELETE /api/v1/users/123

EXPECT WRITE:REDIS DEL user:123
VERIFY command CONTAINS 'DEL'
VERIFY key MATCHES /^user:\d+$/

RESPOND HTTP:204

TEST create-order-audit
RECEIVE HTTP:POST /api/v1/orders
WITH {{order_request.yaml}}

# Ensure all inserts include created_at for audit trails
EXPECT WRITE:MYSQL orders
WITH {{order_data.yaml}}
VERIFY query MATCHES /\bcreated_at\b/
VERIFY query MATCHES /INSERT INTO orders \([^)]+\) VALUES \([^)]+\)/

RESPOND HTTP:201

EXPECT EVENT:<topic_name>
WITH {{<message_payload>}}

EXPECT MESSAGE:<topic_name>
WITH {{<message_payload>}}

EXPECT EVENT:todo-events
WITH {{todo_created_event.yaml}}

# Same as:
EXPECT MESSAGE:todo-events
WITH {{todo_created_event.yaml}}

EXPECT_NOT <CHANNEL> <resource>
[USING_SQL """
<raw-sql-query>
"""]
[USING_SQL_CONTAINS """
<sql-fragment>
"""]

TEST efficient-user-lookup
RECEIVE HTTP:GET /api/v1/users/123

# Assert that we DON'T do a full table scan
EXPECT_NOT READ:MYSQL users
USING_SQL """
SELECT * FROM users
"""

# Should use indexed lookup instead
EXPECT READ:MYSQL users
USING_SQL """
SELECT * FROM users WHERE id = 123 LIMIT 1
"""
RETURNS {{user_response.yaml}}

RESPOND HTTP:200
WITH {{user_response.yaml}}

RESPOND HTTP:<numeric_status_code>
[WITH {{<response_body>}}]
[NOISE
  body.<field_name>
  body.<field_name>]

RESPOND HTTP:201
WITH {{saved_todo.yaml}}
NOISE
  body.id
  body.created_at
  body.updated_at

RESPOND HTTP:<status>
WITH {{response.yaml}}
NOISE
  body.<field_name>
  body.<field_name>

TEST create_todo_success

RECEIVE HTTP:POST /api/v1/todos
WITH {{todo.yaml}}
HEADERS
  Authorization: Bearer token_abc123xyz

EXPECT HTTP:GET http://user-service.local/api/v1/users/auth
HEADERS
  Authorization: Bearer token_abc123xyz
RETURNS {{user_info.yaml}}

EXPECT WRITE:MYSQL todos
WITH {{todo_insert.yaml}}

EXPECT EVENT:todo-events
WITH {{todo_created_event.yaml}}

RESPOND HTTP:201
WITH {{saved_todo.yaml}}
NOISE
  body.id
  body.created_at
  body.updated_at

${VAR_NAME}

{lowercase_var_name}_{16_hex_chars}

TEST authenticate-user
RECEIVE HTTP:POST /api/v1/auth
WITH {{auth_request.yaml}}
HEADERS
  Authorization: Bearer ${API_TOKEN}

EXPECT HTTP:GET http://auth-service.local/validate
HEADERS
  Authorization: Bearer ${API_TOKEN}
RETURNS {{auth_response.yaml}}

RESPOND HTTP:200

RECEIVE HTTP:GET /api/${API_VERSION}/users

EXPECT READ:MYSQL users
USING_SQL """SELECT * FROM users WHERE env = '${DEPLOY_ENV}'"""
RETURNS {{users.yaml}}

api_key: ${API_KEY}
user_id: 123

# The actual API key value is substituted at test time
api_key: api_key_a1b2c3d4e5f6g7h8
status: active

# ─────────────────────────────────────────────
# Service Under Test
# ─────────────────────────────────────────────
service:
  name: notification-service       # Logical name used in container labels
  service_dir: notification-service # Directory containing the service source code
  type: web                        # web | worker | consumer
  framework: fastapi               # rails | fastapi | django | express | chi | custom
                                   # Known frameworks get sensible defaults for start
                                   # command, migration command, and warmup endpoint.
  port: 3002                       # Port the service listens on inside the container
  health_endpoint: /health         # Path polled to confirm the service is ready

  # Docker build / run
  docker_compose: docker-compose.yml  # Path to docker-compose file (relative to service_dir)
  build_context: .                    # Docker build context (relative to .linespec.yml)

  # Override the framework default start command.
  # Use ${PORT} to inject the configured port at runtime.
  start_command: uvicorn app.main:app --host 0.0.0.0 --port 3002

  # Override the framework default migration command (optional).
  migration_command: alembic upgrade head

  # Warmup — wait for the service to accept traffic before running tests.
  needs_warmup: true          # true | false (default: per-framework)
  warmup_endpoint: /health    # Path to poll (overrides framework default)
  warmup_delay_ms: 100        # Extra delay after health check passes (ms)

  # Environment variables injected into the service container at test time.
  environment:
    DATABASE_URL: postgresql+asyncpg://user:pass@db:5432/mydb
    REDIS_URL: redis://redis-proxy:6379
    KAFKA_BROKERS: kafka:29092
    USER_SERVICE_URL: http://user-service:3001/api/v1/users/auth

# ─────────────────────────────────────────────
# Database (omit if external_db: true)
# ─────────────────────────────────────────────
# Single-database form (backward compatible):
database:
  type: postgresql     # mysql | postgresql | mongodb
  image: postgres:16-alpine
  port: 5432
  container: db        # Service name in docker-compose
  init_script: init.sql  # SQL/JS file run on first startup to seed schema
  database: mydb
  username: myuser
  password: mypassword

  # For external databases (not managed by LineSpec):
  host: db.internal    # External host (used when external_db: true)

  # Set to false to disable the protocol-level proxy for this database.
  # Default: true when infrastructure.database is true.
  proxy: true

# Multi-database form — use `databases:` when a service talks to more than
# one database type at the same time (e.g. MySQL + MongoDB).
# Each entry gets its own real-DB container and proxy sidecar.
# The `name:` field is required; `host:` defaults to the entry's name.
databases:
  - name: mysql
    type: mysql
    image: mysql:8.4
    port: 3306
    database: myapp_development
    username: myuser
    password: mypassword
    proxy: true
    # Network aliases assigned automatically:
    #   proxy  → "mysql"       (app connects here)
    #   real   → "real-mysql"  (proxy forwards here)

  - name: mongo
    type: mongodb
    image: mongo:7
    port: 27017
    database: myapp_events
    username: myuser
    password: mypassword
    proxy: true
    # Network aliases: proxy → "mongo", real → "real-mongo"

# Environment variables injected per database when using `databases:`:
#
#   First database also receives legacy unprefixed names:
#     DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD          (mysql)
#     DATABASE_URL                                         (postgresql)
#     MONGODB_URI                                          (mongodb)
#
#   Every database receives a name-prefixed variant:
#     <NAME>_DB_HOST, <NAME>_DB_PORT, ...                 (mysql)
#     <NAME>_DATABASE_URL                                  (postgresql)
#     <NAME>_MONGODB_URI                                   (mongodb)
#
# Example: databases: [{name: mysql, ...}, {name: mongo, ...}] injects
#   DB_HOST=mysql, MYSQL_DB_HOST=mysql, MONGO_MONGODB_URI=mongodb://...

# ─────────────────────────────────────────────
# Infrastructure Flags
# ─────────────────────────────────────────────
infrastructure:
  database: true    # Start and proxy a database container
  kafka: true       # Start a Kafka container for EVENT/MESSAGE expectations
  redis: true       # Start and proxy a Redis interceptor
  grpc: false       # Start a gRPC proxy sidecar
  external_db: false  # true = don't manage the DB container; connect to host above

  # Docker image used for protocol proxy sidecars.
  # Default: linespec:latest
  proxy_image: linespec:latest

# ─────────────────────────────────────────────
# Protobuf descriptor set (optional — gRPC)
# ─────────────────────────────────────────────
# Path to a compiled FileDescriptorSet (.pb) for JSON-to-protobuf conversion.
# When set, RETURNS payloads for gRPC mocks are converted from JSON to binary
# protobuf when the request Content-Type is application/grpc.
# Per-dependency grpc_descriptor_set overrides this value.
grpc_descriptor_set: proto/workflow.pb

# ─────────────────────────────────────────────
# External HTTP / gRPC / service dependencies
# ─────────────────────────────────────────────
dependencies:
- name: user-service
  type: http
  host: user-service.local # Hostname the SUT dials
  port: 3001
  proxy: true # Intercept calls to this host
  host_alias: user-svc # Optional DNS alias inside the test network
  headers: # Default headers added to all matched requests
    X-Internal-Token: secret

- name: workflow-service
  type: grpc
  host: temporal # gRPC upstream hostname (unmocked calls are forwarded here)
  port: 7233
  grpc_descriptor_set: proto/workflow.pb # Optional: overrides service-level default

# ─────────────────────────────────────────────
# Provenance (optional — enables git hooks)
# ─────────────────────────────────────────────
provenance:
  dir: provenance/
  enforcement: warn        # none | warn | strict
  commit_tag_required: true              # require a record ID in commit messages
  auto_affected_scope: true              # auto-populate affected_scope from git diffs
  run_associated_specs_on_complete: true # run associated_specs on the open→implemented transition
  overlap_specs_on_complete: block       # completion-time overlap teeth severity: block | warn | off
  commit_on_status_change: true          # auto-commit after open/complete/deprecate transitions
  manifest_url: ""                       # source manifest URL (set automatically by `linespec clone`)

  # Cross-repo provenance resolution (monorepos / shared product repos)
  cache_ttl_minutes: 60                  # shared_repos cache freshness TTL (default: 60)
  shared_repos:                          # named remote repositories for cross-repo records
    - name: product
      url: https://github.com/acme/product-provenance
      ref: main                          # branch or tag (default: main)
      dir: provenance                    # subdirectory containing the records (default: provenance)

  # Voyage AI embeddings for semantic search
  embedding:
    provider: voyage
    index_model: voyage-4-large
    query_model: voyage-4-lite
    api_key: "${VOYAGE_API_KEY}"
    similarity_threshold: 0.50
    index_on_complete: true

# ─────────────────────────────────────────────
# Container & Network Naming (optional)
# Template variables: {{ .ServiceName }}, {{ .SpecName }}, {{ .Type }}
# ─────────────────────────────────────────────
container_naming:
  database_container: linespec-shared-db
  network_alias: real-db
  kafka_container: linespec-shared-kafka
  proxy_container: proxy-{{ .Type }}-{{ .SpecName }}
  app_container: app-{{ .SpecName }}
  migrate_container: linespec-migrate-{{ .ServiceName }}
  network_name: linespec-shared-net
  project_mount_path: /app/project    # Where the spec directory is mounted
  registry_mount_path: /app/registry  # Where mock payloads are mounted

# ─────────────────────────────────────────────
# Dynamic Port Allocation (optional)
# ─────────────────────────────────────────────
ports:
  dynamic_ports: true       # Allocate random host ports (default: true)
  min_port: 20000           # Lower bound for random port range (default: 10000)
  max_port: 30000           # Upper bound for random port range (default: 65535)
  fixed_proxy_port: 0       # Set to a specific port to pin the verify sidecar (0 = dynamic)

# ─────────────────────────────────────────────
# Schema Discovery (optional — MySQL/PostgreSQL)
# ─────────────────────────────────────────────
schema_discovery:
  mode: auto            # auto | static | none
  tables:               # Used when mode: static
    - users
    - orders
  exclude_tables:       # Tables to ignore in auto mode
    - schema_migrations
    - ar_internal_metadata
  cache_file: .linespec/schema-cache.json

# ─────────────────────────────────────────────
# Payload Loading (optional)
# ─────────────────────────────────────────────
payload:
  directory: payloads       # Subdirectory name for payload files (default: payloads)

# Note: the HTTP proxy reads the response status from a `status` field in the
# RETURNS payload itself (e.g. `status: 401`). This field name is fixed.

# ─────────────────────────────────────────────
# Misc
# ─────────────────────────────────────────────
timeout_seconds: 60     # Per-test timeout in seconds (default: 180)
strict_passthrough: false  # true = fail on any unmatched proxy interaction

service:
  name: my-service
  framework: fastapi
  port: 8000

database:
  type: postgresql
  image: postgres:16-alpine
  port: 5432
  container: db
  database: mydb
  username: myuser
  password: mypassword

infrastructure:
  database: true

linespec test create_todo_success.linespec
linespec test /path/to/linespecs/