Verify a canonical example

What you will build

You will verify the portable foundations canonical example through four distinct evidence layers: source identity, compile/deploy, observed assertions, and a learner API-evidence package. You will deliberately corrupt a copy of the source, watch the identity gate fail, and repair it before any runtime work.

The public receipt set now contains 12 reviewed portable receipts, including Foundations, from bound local Grid runtime runs. This tutorial teaches you to reproduce the Foundations workflow independently. Completing only the local steps earns source contract checked, and a learner-created file remains a receipt candidate until its observations and build provenance pass the trusted ingestion review.

Before you begin

For the source-only portion, you need:

• Node.js 20 or newer;
• jq;
• content/example-verification/contracts.json or the published contract bundle;
• examples/canonical/01-foundations.grid or the exact source downloaded from its example page;
• the verify-source-identity.mjs asset above.

For the runtime portion, you also need a ready Grid Server Build, curl, a public API token, and operator-attested build provenance for the exact Grid binary. These commands use Grid's public API; Runtime Host remains private. Do not invent a build digest or source commit from the product version or catalog digest.

The contract pins Grid version and Grid Core source commit. Read Example verification contracts before treating any generated file as evidence.

1. Select one exact scenario

Inspect the foundations contract:

jq '.examples[]
  | select(.slug == "foundations")
  | {
      slug,
      file,
      source,
      scenarios: [.scenarios[] | {
        id,
        classification,
        capabilities,
        fixtures: (.fixtures // []),
        assertions
      }]
    }' content/example-verification/contracts.json

Deterministic checkpoint:

• scenario ID is authored-baseline;
• classification is portable-exact;
• required capabilities are core;
• the fixture list is empty;
• assertions name B1, B5, and C1.

An empty fixture list is part of this scenario's contract, not a skipped step. Fixture-dependent scenarios pin every fixture path, byte length, and digest before execution.

The reviewed receipt for this scenario is available in the published receipt bundle. Treat it as evidence for its recorded build only; your run needs its own source, runtime, timestamp, and raw API evidence.

2. Verify source identity locally

node verify-source-identity.mjs \
  content/example-verification/contracts.json \
  examples/canonical/01-foundations.grid \
  foundations

Expected checkpoint:

SOURCE CONTRACT CHECKED: foundations 704 bytes e07e35becd5ae03281993b88dcb0acd68d90c9c750684583b2478e73a56930c4 scenarios=1

This checks the exact raw bytes. Formatting, line endings, comments, and trailing newlines all belong to the pinned source identity.

If you are working in this site repository, run the complete contract gate too:

npm run verify:examples

The gate validates schemas, all 29 source identities, fixture identities, scenario matchers, and any checked-in receipts. It does not execute Grid.

3. Deliberately break the source identity

Make a disposable copy and append one comment:

cp examples/canonical/01-foundations.grid /tmp/foundations-mutated.grid
printf '\n# local mutation\n' >> /tmp/foundations-mutated.grid

node verify-source-identity.mjs \
  content/example-verification/contracts.json \
  /tmp/foundations-mutated.grid \
  foundations

Expected failure: exit status 1 and a SOURCE MISMATCH line containing both expected and actual byte/digest pairs.

Minimal repair is to restore the exact source bytes, not to update the contract around an unreviewed change:

cp examples/canonical/01-foundations.grid /tmp/foundations-repaired.grid
node verify-source-identity.mjs \
  content/example-verification/contracts.json \
  /tmp/foundations-repaired.grid \
  foundations

The repaired copy returns the exact checkpoint from step 2.

4. Discover the runtime capability before compiling

For the remaining steps:

export GRID_URL="http://localhost:3000"
export GRID_TOKEN="replace-with-your-api-token"

Check readiness and capture the runtime's advertised product identity:

curl --fail-with-body "$GRID_URL/readyz" | jq '{status, probes}'

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_TOKEN" \
  "$GRID_URL/api/capabilities" \
  | tee /tmp/foundations-capabilities.json \
  | jq '{schemaVersion, productVersion, catalogSha256}'

The contract's core value is a review taxonomy label, not a key advertised by the Runtime catalog. Confirm that the complete capability response has the expected product version and catalog identity for the reviewed build. Those values are compatibility evidence; neither substitutes for the receipt's exact build SHA-256 or for observed behavior.

5. Compile by deploying the exact source

Construct the request directly from the repaired source:

jq -n --rawfile source /tmp/foundations-repaired.grid '{
  id: "verify-foundations",
  protectedMode: false,
  source: $source
}' > /tmp/foundations-deploy.json

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$GRID_URL/api/models" \
  --data-binary @/tmp/foundations-deploy.json \
  | tee /tmp/foundations-deployed.json \
  | jq '{id, sourceHash, diagnostics}'

A successful deployment proves the exact source was accepted by this running build's compile/deploy path. Verify that the returned source identity corresponds to the submitted source and retain all diagnostics. A source contract alone would not prove this step.

This exported Foundations source predates the protected-mode I/O decorator contract, so the verification model is deployed unprotected and receives no writes. Do not alter canonical source merely to add decorators around a test harness.

If compilation fails, preserve parseDiagnostic with its code, message, span, snippet, and raw compiler message. Repair the source only through a reviewed contract update; do not silently normalize the canonical file.

6. Capture the three runtime observations

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$GRID_URL/api/models/verify-foundations/symbols/resolve" \
  --data '{"symbols":["B1","B5","C1"]}' \
  > /tmp/foundations-resolved.json

jq '[
  {
    assertionId: "margin",
    actual: {kind: .R1C2.value.kind, value: .R1C2.value.value},
    passed: (.R1C2.status == "ready" and .R1C2.value.kind == "number" and .R1C2.value.value == 39000)
  },
  {
    assertionId: "tax-due",
    actual: {kind: .R5C2.value.kind, value: .R5C2.value.value},
    passed: (.R5C2.status == "ready" and .R5C2.value.kind == "number" and .R5C2.value.value == 7665)
  },
  {
    assertionId: "status",
    actual: {kind: .R1C3.value.kind, value: .R1C3.value.value},
    passed: (.R1C3.status == "ready" and .R1C3.value.kind == "string" and .R1C3.value.value == "watch")
  }
]' /tmp/foundations-resolved.json \
  | tee /tmp/foundations-observations.json \
  | jq -e 'all(.[]; .passed == true)'

Expected live checkpoint: the final command prints true. The actual fields came from the response; they were not copied from the contract.

The request uses authored symbols B1, B5, and C1, but this API response is keyed by their normalized coordinates R1C2, R5C2, and R1C3; each snapshot's symbol field uses the same normalized coordinate. Preserve the complete raw response as evidence and map it deliberately to the contract assertion IDs.

If one assertion fails, preserve the complete symbol snapshots and runtime identity. Repair model setup or investigate semantic drift; never change passed by hand.

7. Assemble a learner evidence package

Obtain these values from trusted sources:

• CONTRACT_SHA256: raw SHA-256 of the complete contract file used in step 1;
• GRID_BUILD_SHA256: operator-attested digest of the exact Grid build that executed the model;
• GRID_BUILD_SOURCE_COMMIT: exact source commit embedded in or attested for that build;
• GRID_BUILD_DIRTY: JSON boolean recording whether that source checkout was dirty; trusted ingestion currently accepts only false;
• GRID_BUILD_PROFILE: exact build profile, such as a reviewed release or debug-lite profile;
• GRID_PLATFORM: exact platform identifier for that build;
• GRID_VERSION: product version reported by that runtime.

export CONTRACT_SHA256="$(shasum -a 256 content/example-verification/contracts.json | awk '{print $1}')"
export GRID_BUILD_SHA256="replace-with-64-hex-build-digest"
export GRID_BUILD_SOURCE_COMMIT="replace-with-40-or-64-hex-source-commit"
export GRID_BUILD_DIRTY=false
export GRID_BUILD_PROFILE="replace-with-exact-build-profile"
export GRID_PLATFORM="replace-with-exact-platform"
export GRID_VERSION="replace-with-reported-product-version"
export DEPLOYED_SOURCE_HASH="$(jq -r '.sourceHash' /tmp/foundations-deployed.json)"

jq -n \
  --arg contractSha256 "$CONTRACT_SHA256" \
  --arg buildSha256 "$GRID_BUILD_SHA256" \
  --arg buildSourceCommit "$GRID_BUILD_SOURCE_COMMIT" \
  --argjson buildDirty "$GRID_BUILD_DIRTY" \
  --arg buildProfile "$GRID_BUILD_PROFILE" \
  --arg platform "$GRID_PLATFORM" \
  --arg gridVersion "$GRID_VERSION" \
  --arg sourceHash "$DEPLOYED_SOURCE_HASH" \
  --arg observedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --slurpfile observations /tmp/foundations-observations.json \
  --slurpfile resolved /tmp/foundations-resolved.json \
  '{
    candidateKind: "learner-api-evidence-v1",
    contractSha256: $contractSha256,
    exampleSlug: "foundations",
    scenarioId: "authored-baseline",
    sourceSha256: "e07e35becd5ae03281993b88dcb0acd68d90c9c750684583b2478e73a56930c4",
    fixtureSha256s: [],
    runtime: {
      gridVersion: $gridVersion,
      buildSha256: $buildSha256,
      buildSourceCommit: $buildSourceCommit,
      buildDirty: $buildDirty,
      buildProfile: $buildProfile,
      platform: $platform
    },
    scenarioCapabilityLabels: ["core"],
    observedAt: $observedAt,
    observations: $observations[0],
    evidence: {
      observationMethod: "public-coordinate-api-v1",
      transport: "local-grid-api",
      modelId: "verify-foundations",
      sourceHash: $sourceHash,
      requestedBindings: {
        B1: "R1C2",
        B5: "R5C2",
        C1: "R1C3"
      },
      resolvedSnapshots: {
        R1C2: $resolved[0].R1C2,
        R5C2: $resolved[0].R5C2,
        R1C3: $resolved[0].R1C3
      }
    },
    passed: ($observations[0] | all(.[]; .passed == true))
  }' > /tmp/foundations-api-evidence.json

jq . /tmp/foundations-api-evidence.json

This package keeps the authored-to-normalized binding map separate from raw coordinate-keyed API snapshots, which makes it useful for learning, debugging, and review. It is deliberately not an admissible repository receipt: checked-in receipts require the managed adapter's direct, authenticated Runtime RPC transport plus both capability-catalog fingerprints pinned to reviewed binary provenance. Maintainers produce that evidence with npm run capture:example-receipts -- --example foundations --replace and an exact GRID_RUNTIME_HOST_BIN. A dirty build remains useful debugging evidence, but trusted capture rejects it. Copying expected values into actual is not execution evidence.

8. Clean up the temporary model

curl --fail-with-body \
  -H "Authorization: Bearer $GRID_TOKEN" \
  -X DELETE "$GRID_URL/api/models/verify-foundations"

Expected response: true.

You are done when

• The exact source passes its byte-and-digest contract.
• A disposable mutation fails and restoring exact bytes repairs the failure.
• You retained the running build's product/catalog identity and it accepts the exact source.
• All three actual runtime observations pass without hand-edited evidence.
• The learner evidence package binds the contract, source, empty fixture set, build claims, scenario labels, raw API snapshots, and observation time without posing as a trusted receipt.
• You label the result runtime verified only after managed Runtime RPC capture and the repository verifier accept it.

For schema and matcher details, use Example verification contracts. For compile failures, see Troubleshoot Grid.