Function Manifest

Relay packages function metadata in a function.relay.json manifest plus a companion lockfile (function.lock.json). These files capture runtime requirements, dependency declarations, and automation scripts so builds can be reproduced across environments.

Manifest (function.relay.json)

function.relay.json

{
  "schemaVersion": "1.0",
  "name": "payments-handler",
  "description": "Capture Stripe payment intents",
  "entrypoint": "handler:main",
  "runtime": {
    "language": "python",
    "version": "3.11"
  },
  "dependencies": {
    "pip": [
      {"name": "requests", "version": "==2.32.3"},
      {"name": "tenacity", "version": "^8.2"}
    ],
    "system": ["libpq-dev"]
  },
  "environment": {
    "STRIPE_API_KEY": "required"
  },
  "scripts": {
    "post_install": "python scripts/bootstrap.py"
  },
  "metadata": {
    "owner": "payments-team",
    "tier": "critical"
  }
}

Schema highlights

Field	Description
schemaVersion	Manifest version (currently 1.0).
runtime	Language + optional platform hint used by the execution sandbox.
dependencies.pip	PyPI dependencies using name + optional version spec and source.
environment	Environment variables and whether they are required.
scripts	Optional automation commands (post-install hooks, migrations).
metadata	Free-form annotations (team ownership, tags, SLAs).

The manifest schema is published in schemas/function_manifest.schema.json for tooling integration.

Lockfile (function.lock.json)

The lockfile pins resolved dependency versions. Relay generates it automatically when the manifest is ingested; you can also provide a pre-resolved file when promoting builds from CI.

function.lock.json

{
  "schemaVersion": "1.0",
  "generated_at": "2025-10-10T12:15:00Z",
  "generator": "relay-protocol",
  "manifest_digest": "6a6e4a7d5cd8…",
  "dependencies": {
    "pip": [
      {"name": "requests", "version": "2.32.3", "source": "pypi"},
      {"name": "tenacity", "version": "8.2.3", "source": "pypi"}
    ],
    "system": ["libpq-dev"]
  }
}

Lockfiles reference the manifest via manifest_digest (SHA-256 of the canonical manifest JSON). Relay rejects lockfiles whose digest does not match the manifest supplied with the request.

Backend ingestion

• POST /api/v1/functions/create accepts manifest and optional lockfile fields. The server validates the payload, computes a lockfile when needed, and persists both structures alongside the function definition.
• Every function version stores the manifest + lockfile snapshot. The version ledger (function_version_ledger) includes the artifacts inside manifest_snapshot so branch heads can be reconstructed without hitting the primary tables.
• RUFID resolution via the cached service now returns the manifest and lockfile, ensuring deploy tooling and the orchestration engine operate against consistent dependency data.

CLI workflow

1. Place function.relay.json next to your source code.
2. Run relay functions manifest install (optionally with --path / --lockfile) to materialize function.lock.json and capture a SHA-256 digest of the manifest.
3. Run relay functions manifest verify before committing to ensure the lockfile digest stays in sync with the manifest.
4. Deploy or invoke with relay functions deploy --code ./src --branch dev --branch-key … (or relay functions invoke --branch dev) to publish and execute against the branch-scoped manifest.
5. The CLI automatically prints resolved versions from the server response, and relay functions export emits both manifest + lockfile for portability.

relay functions manifest install uses canonical JSON encoding to compute the digest and sorts dependency lists before writing the lockfile, ensuring deterministic diffs in Git. Pair it with relay functions manifest verify in CI to fail fast when manifests drift from their lockfiles. Curated examples live under examples/functions/, and make manifest-install-example regenerates their lockfiles so smoke coverage stays representative. Note that the CLI is written in Go—install Go 1.22+ (verify with go version) before running these commands locally or in CI containers.

Next steps

• FN-107 will introduce full dependency resolution (pinning, integrity hashes, private registries).
• FN-205 will extend manifests with marketing metadata for registry previews.