{"id":"ops/activity-adoption-proof","relativePath":"ops/activity-adoption-proof.md","title":"Activity Feed Adoption Proof Runbook","markdown":"# Activity Feed Adoption Proof Runbook\n\nThis runbook supports the Era C exit-gate target: at least three declared external Linked Art systems consume `/api/activity` within the adoption window.\n\nThe command below records a partner-owned declared consumer ID by sending `x-linked-art-consumer-id` to `/api/activity`, then reads `/api/activity/readiness` to confirm the deployment observed that declared external consumer.\n\n## Command\n\n```bash\nBASE_URL=https:// \\\nMETAMUSEUM_ACTIVITY_CONSUMER_ID= \\\npnpm activity:adoption:probe\n```\n\nEquivalent explicit form:\n\n```bash\npnpm activity:adoption:probe -- --base-url https:// --consumer-id \n```\n\nTo prove the full three-consumer checkpoint in one run after all partner IDs are known:\n\n```bash\nBASE_URL=https:// \\\nMETAMUSEUM_ACTIVITY_CONSUMER_IDS=wikibase-cloud-prod,partner-harvest-bot,analytics-reader-prod \\\npnpm activity:adoption:matrix\n```\n\nEquivalent explicit form:\n\n```bash\npnpm activity:adoption:matrix -- \\\n --base-url https:// \\\n --consumer-id wikibase-cloud-prod \\\n --consumer-id partner-harvest-bot \\\n --consumer-id analytics-reader-prod\n```\n\nArtifacts:\n\n- `artifacts/activity-adoption/activity-adoption-proof-latest.json`\n- `artifacts/activity-adoption/runs/activity-adoption-proof-.json`\n- `artifacts/activity-adoption/activity-adoption-matrix-latest.json`\n- `artifacts/activity-adoption/runs/activity-adoption-matrix-.json`\n\n## Consumer ID Rules\n\n- Use a stable ID owned by the external consumer, for example `wikibase-cloud-prod` or `partner-harvest-bot`.\n- Do not use placeholder IDs such as `test-*`, `demo-*`, `example-*`, `local-*`, or localhost-oriented names for production evidence.\n- The command rejects placeholder/local-looking IDs by default. `--allow-placeholder` exists only for local rehearsals.\n\n## Pass Criteria\n\nThe proof report has `status: \"pass\"` when:\n\n- `/api/activity` returns HTTP 2xx.\n- `/api/activity/readiness` returns HTTP 2xx.\n- Readiness telemetry contains the provided consumer ID as:\n - `class: \"declared\"`\n - matching `declaredId`\n - `isExternal: true`\n - non-empty `lastSeenAt`\n\nThe overall adoption exit gate still requires three unique declared external consumers within the configured window. A single passing proof only confirms one consumer was observed.\n\nThe matrix report has `status: \"pass\"` only when every requested consumer probes `/api/activity` successfully, every requested consumer appears in readiness as declared/external, and `/api/activity/readiness` reports the `>=3` checkpoint as ready.\n\n## Partner Hand-Off\n\nSend partners this minimum request:\n\n```bash\ncurl -H \"Accept: application/json\" \\\n -H \"x-linked-art-consumer-id: \" \\\n \"https:///api/activity?limit=1\"\n```\n\nAfter the partner runs it, operators can verify:\n\n```bash\ncurl \"https:///api/activity/readiness\"\npnpm activity:adoption:matrix -- --base-url https:// --consumer-ids ,,\npnpm era-c:exit-gate:evidence\n```\n\n## Evidence Hygiene\n\n- Derived fingerprints are diagnostic only and do not satisfy the gate.\n- Operators must not run production proof with internal placeholder IDs.\n- Keep partner IDs stable across checks so the 30-day activity window reflects real adoption.\n","sections":[{"level":2,"heading":"Command","anchor":"command"},{"level":2,"heading":"Consumer ID Rules","anchor":"consumer-id-rules"},{"level":2,"heading":"Pass Criteria","anchor":"pass-criteria"},{"level":2,"heading":"Partner Hand-Off","anchor":"partner-hand-off"},{"level":2,"heading":"Evidence Hygiene","anchor":"evidence-hygiene"}],"html":"

Activity Feed Adoption Proof Runbook

\n

This runbook supports the Era C exit-gate target: at least three declared external Linked Art systems consume `/api/activity` within the adoption window.

\n

The command below records a partner-owned declared consumer ID by sending `x-linked-art-consumer-id` to `/api/activity`, then reads `/api/activity/readiness` to confirm the deployment observed that declared external consumer.

\n

Command

\n
\nBASE_URL=https://<deploy-host> \\\nMETAMUSEUM_ACTIVITY_CONSUMER_ID=<partner-owned-consumer-id> \\\npnpm activity:adoption:probe\n
\n

Equivalent explicit form:

\n
\npnpm activity:adoption:probe -- --base-url https://<deploy-host> --consumer-id <partner-owned-consumer-id>\n
\n

To prove the full three-consumer checkpoint in one run after all partner IDs are known:

\n
\nBASE_URL=https://<deploy-host> \\\nMETAMUSEUM_ACTIVITY_CONSUMER_IDS=wikibase-cloud-prod,partner-harvest-bot,analytics-reader-prod \\\npnpm activity:adoption:matrix\n
\n

Equivalent explicit form:

\n
\npnpm activity:adoption:matrix -- \\\n  --base-url https://<deploy-host> \\\n  --consumer-id wikibase-cloud-prod \\\n  --consumer-id partner-harvest-bot \\\n  --consumer-id analytics-reader-prod\n
\n

Artifacts:

\n
  • `artifacts/activity-adoption/activity-adoption-proof-latest.json`
  • `artifacts/activity-adoption/runs/activity-adoption-proof-<timestamp>.json`
  • `artifacts/activity-adoption/activity-adoption-matrix-latest.json`
  • `artifacts/activity-adoption/runs/activity-adoption-matrix-<timestamp>.json`
\n

Consumer ID Rules

\n
  • Use a stable ID owned by the external consumer, for example `wikibase-cloud-prod` or `partner-harvest-bot`.
  • Do not use placeholder IDs such as `test-`, `demo-`, `example-`, `local-`, or localhost-oriented names for production evidence.
  • The command rejects placeholder/local-looking IDs by default. `--allow-placeholder` exists only for local rehearsals.
\n

Pass Criteria

\n

The proof report has `status: "pass"` when:

\n
  • `/api/activity` returns HTTP 2xx.
  • `/api/activity/readiness` returns HTTP 2xx.
  • Readiness telemetry contains the provided consumer ID as:
  • `class: "declared"`
  • matching `declaredId`
  • `isExternal: true`
  • non-empty `lastSeenAt`
\n

The overall adoption exit gate still requires three unique declared external consumers within the configured window. A single passing proof only confirms one consumer was observed.

\n

The matrix report has `status: "pass"` only when every requested consumer probes `/api/activity` successfully, every requested consumer appears in readiness as declared/external, and `/api/activity/readiness` reports the `>=3` checkpoint as ready.

\n

Partner Hand-Off

\n

Send partners this minimum request:

\n
\ncurl -H "Accept: application/json" \\\n  -H "x-linked-art-consumer-id: <partner-owned-consumer-id>" \\\n  "https://<deploy-host>/api/activity?limit=1"\n
\n

After the partner runs it, operators can verify:

\n
\ncurl "https://<deploy-host>/api/activity/readiness"\npnpm activity:adoption:matrix -- --base-url https://<deploy-host> --consumer-ids <id-1>,<id-2>,<id-3>\npnpm era-c:exit-gate:evidence\n
\n

Evidence Hygiene

\n
  • Derived fingerprints are diagnostic only and do not satisfy the gate.
  • Operators must not run production proof with internal placeholder IDs.
  • Keep partner IDs stable across checks so the 30-day activity window reflects real adoption.
","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"68a80b43ae582bc2fe8af85cd8992771b65da97b848cf5c5f1b7036b5e70fe65","checksumPrefix":"68a80b43ae58","anchorCount":5,"lineCount":91,"rawUrl":"/api/docs/content?path=ops%2Factivity-adoption-proof.md","htmlUrl":"/docs?doc=ops%2Factivity-adoption-proof.md","apiUrl":"/api/docs/content?path=ops%2Factivity-adoption-proof.md"}