Data model

The platform has three core persistence models:

• The Neptune knowledge graph holds durable development knowledge and traceability: requirements, decisions, artifacts, derived items, provenance, and their relationships.
• The DynamoDB execution model holds the operational state of an intent run: stages, gates, events, outputs, metrics, construction lanes, and integration waits.
• The DynamoDB blocks and workflows model holds the versioned methodology library and executable workflow compositions.

These models have different responsibilities. DynamoDB is the source of truth for orchestration and scheduling; Neptune is the source of truth for the knowledge and traceability agents consume. The methodology library supplies the pinned workflow and blocks used to construct each execution plan.

Earlier releases used a sprint-scoped graph and separate agent execution tables. That v1 model is read-only and is not the normative model described here.

Neptune knowledge graph

The graph keeps a requirement, the decision behind it, the work that implements it, and the resulting pull request connected. The canonical artifact is its authored Markdown document. Sections, typed items, citations, and their traceability edges are derived projections that can be rebuilt deterministically.

Conceptual model

graph TD
  PROJECT["Project"]
  INTENT["Intent"]
  ARTIFACT["Artifact<br/>canonical Markdown"]
  SECTION["Section<br/>derived heading"]
  ITEM["Typed item<br/>Requirement, Story, Persona,<br/>Component, Decision, Contract,<br/>StoryMapEntry"]
  UNIT["UnitOfWork"]
  QUESTION["Question"]
  STEERING["Steering"]
  DISCUSSION["Discussion"]
  MESSAGE["DiscussionMessage"]
  PR["PullRequest / UnitPullRequest"]
  KNOWLEDGE["TeamKnowledge / LearningRule"]

  PROJECT -->|HAS_KNOWLEDGE / HAS_LEARNING| KNOWLEDGE
  KNOWLEDGE -.->|INFORMS| INTENT

  INTENT -->|CONTAINS| ARTIFACT
  INTENT -->|CONTAINS| QUESTION
  INTENT -->|CONTAINS| STEERING
  INTENT -->|CONTAINS| UNIT
  INTENT -->|HAS_DISCUSSION| DISCUSSION
  INTENT -->|HAS_PR / HAS_UNIT_PR| PR

  ARTIFACT -->|HAS_SECTION| SECTION
  ARTIFACT -->|HAS_ITEM| ITEM
  ARTIFACT -->|PRODUCES / CONSUMES /<br/>DERIVED_FROM / RELATES_TO /<br/>DEPENDS_ON / CITES| ARTIFACT

  ITEM -->|COVERS / FOR_PERSONA /<br/>IMPLEMENTS / DEPENDS_ON| ITEM
  ITEM -->|IMPLEMENTS| UNIT
  SECTION -->|DERIVED_FROM| ARTIFACT
  ITEM -->|DERIVED_FROM| ARTIFACT
  UNIT -->|DERIVED_FROM| ARTIFACT
  UNIT -->|DEPENDS_ON| UNIT
  UNIT -->|EXPOSES / CONSUMES_CONTRACT| ITEM

  QUESTION -.->|INFLUENCES| ARTIFACT
  STEERING -.->|REVISES| QUESTION
  STEERING -.->|INFLUENCES| ARTIFACT
  DISCUSSION -.->|DISCUSSES| ARTIFACT
  DISCUSSION -->|HAS_MESSAGE| MESSAGE

The diagram is intentionally conceptual. Some relationships can target more than one entity type, and the Graph page omits section vertices to keep the visual topology readable.

Graph layers

Artifact layer

The artifact layer contains the intent, its canonical documents, human input, provenance, discussions, knowledge, and delivery records. It is the compact default shown on the Graph page.

Agents may create relationships between artifacts only from the explicit business-edge allowlist. They cannot invent arbitrary edge labels.

Derived item layer

After an artifact is written, deterministic parsers inspect its Markdown:

1. Markdown H2–H6 headings become Section vertices; H1 is excluded.
2. Registered fenced-YAML blocks become typed item vertices.
3. [[artifact-type]] references create CITES edges to matching artifacts.
4. Relationship fields such as covers, persona, and depends_on become typed edges.
5. The execution unit plan is mirrored as UnitOfWork vertices and edges.

Agents write documents and structured blocks, not graph topology. The derived layer is an index over those documents and can be regenerated.

Vertex types

Scope and authored knowledge

Derived structure

The typed-item list and field definitions come from the extraction registry in lambda/shared/artifact-extractors.js. That registry is the implementation source of truth: adding a registered type automatically extends extraction, validation, agent authoring instructions, and graph reads.

Edge types

Scope and ownership

Artifact relationships

Traceability and provenance

INFORMS is synthesized in the graph API projection to show prompt injection; Neptune persists the knowledge vertices under Project through HAS_KNOWLEDGE and HAS_LEARNING.

Identity, provenance, and lifecycle

Every intent-scoped write carries trusted provenance rather than relying on agent-supplied metadata. Common fields include:

• project_id and intent_id
• created_by_execution_id and created_by_stage_instance_id
• section_index and unit_slug for parallel construction lanes
• stage_attempt
• created_at

Artifact IDs are chosen by agents and are only unique within an intent. Artifact and section lookups are therefore always scoped by intent_id. Derived item IDs include their intent and type, while questions, steering, and other operational vertices use globally unique or deterministic IDs.

A logical artifact keeps a stable current head. Rewinds and edits preserve history:

• ArtifactVersion records immutable prior content.
• superseded_at and superseded_by mark lineage without deleting history.
• Normal graph, context, and search reads expose only current logical heads.
• Re-running a stage can rehabilitate a superseded logical artifact while retaining its lineage.

What the Graph page shows

The Graph page is a projection of the stored model, not a raw database browser. It:

• defaults to artifacts and provenance;
• optionally adds typed items and units;
• excludes Section nodes to avoid overwhelming the canvas;
• excludes superseded or stale derived rows from normal views;
• drops edges whose endpoints are outside the rendered intent subgraph.

For the runtime behavior that creates and consumes this graph, see the execution model. For the UI, see The graph page.

DynamoDB execution model

The v2 executions table is the durable process model for intent execution. It answers operational questions that do not belong in the knowledge graph:

• What state is the execution or a stage in?
• Which human gate is waiting for an answer?
• Which construction lanes are ready, running, blocked, or complete?
• What output, metrics, sensor results, and graph reads did a stage produce?
• Which pull-request or tracker operation must be checked again?

The table uses a composite-key single-table design. Every record for one run is grouped in the same partition:

pk = EXEC#<executionId>

The sort key identifies the record type and, where ordering matters, includes a timestamp or sequence:

graph LR
  PARTITION["EXEC#<executionId>"]
  META["META<br/>execution header"]
  STAGE["STAGE#&lt;stageInstanceId&gt;"]
  HUMAN["HUMAN#&lt;humanTaskId&gt;"]
  EVENT["EVENT#&lt;timestamp&gt;#&lt;eventId&gt;"]
  OUTPUT["OUTPUT#&lt;sequence&gt;"]
  OBS["METRIC#… / SENSOR#… / READ#…"]
  UNITPLAN["UNITPLAN"]
  UNIT["UNIT#&lt;laneId&gt;"]
  DELIVERY["UNITPR#… / FEEDBACK#…"]
  ACTIONS["STEER#… / QEDIT#… / COMPOSE#…"]
  SYNC["TRACKERSYNC"]

  PARTITION --> META
  PARTITION --> STAGE
  PARTITION --> HUMAN
  PARTITION --> EVENT
  PARTITION --> OUTPUT
  PARTITION --> OBS
  PARTITION --> UNITPLAN
  PARTITION --> UNIT
  PARTITION --> DELIVERY
  PARTITION --> ACTIONS
  PARTITION --> SYNC

Record types

UNITPLAN and UNIT#… rows are the scheduling source of truth. Their UnitOfWork representation in Neptune is a traceability and UI projection; the orchestrator never schedules work from the graph.

Indexes and access patterns

The table has three global secondary indexes:

GSI3 currently groups three kinds of live work:

Relationship to the graph

The execution and graph models are joined by stable application identifiers, not by database-level foreign keys:

An intent can have a DynamoDB META row while it is still a draft and before its Neptune Intent vertex exists. Starting the intent creates the graph anchor; subsequent stages update process state in DynamoDB and write knowledge artifacts to Neptune.

Lifecycle characteristics

Different records have different update behavior:

• Execution, stage, human-task, unit, pull-request, and synchronization rows are updated as their state machines advance.
• Events, outputs, metrics, sensor results, and graph-read records form ordered execution history.
• Rewinds reset the affected executable state while preserving audit context through events, steering, attempts, and graph lineage.
• Durable callbacks are stored with waiting work so an execution can suspend without consuming compute and resume from the same point.

The key builders and record constructors in lambda/shared/v2-process-keys.js are the implementation source of truth. The read/write behavior is centralized in lambda/shared/v2-process-store.js.

DynamoDB blocks and workflows model

Building blocks and workflows share one composite-key DynamoDB table. Blocks occupy one partition per reusable definition; workflows occupy one partition per composition.

Building blocks

pk = BLOCK#<tenant>#<TYPE>#<id>
sk = V#latest | V#<version>

V#latest is the mutable current record. Each numbered V#<version> record is an immutable snapshot. The catalog index lists the current blocks of one type:

GSI1PK = TENANT#<tenant>#<TYPE>
GSI1SK = <name>

Large Markdown bodies and sensor scripts are stored content-addressed in S3. The DynamoDB record carries bodyRef and scriptRef pointers containing the S3 key, SHA-256 hash, and byte count.

Workflows

pk = WF#<tenant>#<workflowId>

One partition contains the complete live composition:

Every workflow mutation creates an immutable snapshot by copying the live rows under V#<version>#<live-sort-key>. A single partition query therefore loads either the current composition or an exact historical version. The META row uses the catalog index key TENANT#<tenant>#WORKFLOW.

Ownership and execution

The table has two ownership namespaces:

• SYSTEM contains the read-only imported baseline.
• default contains user-created and forked definitions.

A default definition shadows the SYSTEM definition with the same identifier. When an intent starts, its execution metadata pins a numbered workflow version, so later workflow edits cannot change the running plan.

The key schemes in lambda/shared/blocks.js and lambda/shared/workflows.js are the implementation sources of truth.

For the surrounding AWS components and other storage services, see Architecture.