Metadata Schema¶

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Reviewed 2026-10-09

Required deltas (from the 2026-10-08 packet, re-validated): distinguish trusted tenant/project/caller scope (derived from authentication) from untrusted request or prompt fields; separate run, step, attempt, message, tool-invocation/effect, approval and artifact identities; traceId is diagnostic, not an idempotency key or permission; idempotency is unique per trusted scope and operation (same key + same input = same result, changed input = conflict) with stated retention; add schemaVersion and inbox deduplication identity; bind approvals to the exact action/artifact hash and concurrency version; record external effect identity, receipt and uncertain outcome; define classification, redaction and retention for metadata, inputs, outputs and traces separately. No field here exists in AgentTraceContext today beyond trace, blueprint, origin and workflow step (ADR-0014).

Every persisted entity, published event, and produced artifact in the factory carries a common set of cross-cutting metadata fields. These fields are the backbone of traceability and multi-tenant isolation, and they are what allow the Knowledge Platform and Observability & Feedback Platform to correlate everything to a single lifecycle.

Cross-cutting fields¶

Field	Type	Applies to	Purpose
`tenantId`	string	all	Owning tenant; isolation boundary enforced in every store and handler.
`projectId`	string	project-scoped	Factory project (the SaaS being produced).
`moduleId`	string	module-scoped	Module: microservice, UI, worker, library, or gateway.
`traceId`	string	all	End-to-end lifecycle trace from intent to runtime feedback.
`correlationId`	string	events, tasks	Correlates all activity within one workflow.
`causationId`	string	events	The id of the directly causing event.
`agentId`	string	agent-produced	Which agent produced or acted on this.
`skillId`	string	skill-produced	Which skill execution produced this.
`artifactId`	string	artifact-linked	The artifact this record concerns.
`environment`	enum	runtime-scoped	`dev`, `test`, `staging`, `prod`.
`version`	string (semver)	versioned	Version of the entity/artifact/contract.
`createdAt`	ISO-8601 UTC	all	Creation timestamp.
`updatedAt`	ISO-8601 UTC	mutable	Last update timestamp.
`status`	enum	stateful	Lifecycle status of the entity (context-specific).

How the fields connect the lifecycle¶

flowchart LR
    Intent["Intent / Goal<br/>traceId"] --> Blueprint["Blueprint<br/>projectId"]
    Blueprint --> Task["AgentTask<br/>agentId, skillId"]
    Task --> Artifact["Artifact<br/>artifactId, moduleId"]
    Artifact --> Deploy["Deployment<br/>environment, version"]
    Deploy --> Signal["RuntimeSignal<br/>traceId"]
    Signal --> Intent

Hold "Alt" / "Option" to enable pan & zoom

A single traceId is minted when intent enters the factory and is propagated through every blueprint, agent task, artifact, commit, pipeline, deployment, and runtime signal. correlationId groups the events of one workflow; causationId chains cause to effect.

Idempotency keys¶

Worker-triggered operations derive an idempotency key so retries and duplicate deliveries are safe:

idempotencyKey = sha256( eventId + ":" + handlerName + ":" + targetAggregateId )

The key is stored with the operation result so a replay returns the original outcome rather than re-executing side effects. See the per-platform workers.md pages for the concrete key used by each worker.

Persistence rules¶

All metadata fields are first-class columns (relational stores) or top-level properties (document stores), never buried inside a serialized blob, so they are queryable and indexable.
tenantId is part of every primary or secondary index used for tenant-scoped queries.
traceId, correlationId, projectId, and moduleId are indexed wherever cross-entity correlation queries are expected.
Sensitive payloads are classified and may be redacted; the metadata fields themselves are never redacted because they carry no business secrets (see Artifact Metadata and the Knowledge Platform governance).