Skip to content

Metadata Schema

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).