---

id: data-model kind: architecture title: Data Model status: active #

Data Model #

Charter's database model should make the spec workspace, event stream, consumer agents, packets, and provenance explicit in Jazz.

The code currently implements the first core slice: project root, documents, versions, events, work items, registered agent consumers, durable agent packets, and agent requests. The target product still adds spans, comments, and richer activity records beyond the current request-prompt compatibility layer.

CharterProject #

One root per repository or logical project.

Current fields:

• projectId: stable project identity.
• name: display name.
• documents: map of document id to current SpecDocument.
• versions: map of version id to immutable SpecDocumentVersion.
• events: Jazz CoFeed of append-only ProjectEvent entries.
• workItems: map of mutable WorkItem CoMaps keyed by work item id.
• consumers: map of consumer id to AgentConsumer.
• packets: map of packet id to durable WorkPacket / AgentPacket.
• requests: map of request id to database-backed AgentRequest.
• updatedAt: last materialization time.

Target fields:

• spans: map of span id to DocumentSpan.
• comments: map of comment id to DocumentComment.
• activity: feed or map of AgentActivity records.

SpecDocument #

Current materialized state for a spec document.

Fields:

• id: stable document id.
• path: POSIX path relative to spec/.
• title: frontmatter title or first H1 fallback.
• kind: normalized broad category.
• status: lifecycle state.
• body: Markdown body without frontmatter.
• frontmatterJson: normalized JSON string for frontmatter.
• headingsJson: extracted heading outline.
• sha256: content hash of the raw file or equivalent Markdown projection.
• sizeBytes: raw content byte length.
• mtimeMs: filesystem modification time when the source is a file.
• importedAt: import timestamp.

Target document rows should support rich editor state without losing Markdown projection. The minimal path can keep Markdown body as text. A richer path can add editor/co-rich-text state once the front end earns it.

SpecDocumentVersion #

Immutable content snapshot keyed by document id and hash.

Version rows let agents compare old and new requirements without pretending the current row is the whole history. The Jazz adapter creates a SpecDocumentVersion CoMap for each new documentId:sha256 it sees and leaves prior versions addressable through CharterProject.versions.

DocumentSpan #

A span points to a region inside a document.

Fields:

• id: stable span id.
• documentId: target document.
• documentVersionId: version or hash at creation time.
• startOffset / endOffset: text offsets for the first version.
• anchorJson: optional richer Markdown-aware anchor.
• quotedText: text snapshot at creation time.
• status: active, resolved, stale, archived.
• createdBy / createdAt.

Spans are how a user highlights part of a spec and asks Charter to do something with that exact region.

DocumentComment #

A comment attaches to a document or span.

Fields:

• id.
• documentId.
• spanId when applicable.
• body.
• kind: comment, action-request, resolution-note.
• status: open, resolved, archived.
• assignedConsumerId when applicable.
• createdBy / createdAt / updatedAt.

Action comments should create project events and, when actionable, work items.

ProjectEvent #

Append-only semantic event entry in the CharterProject.events CoFeed. Raw field-level provenance lives in Jazz edit history via $jazz.getEdits(); ProjectEvent is the agent/UI-facing classification layer over that history.

Initial event types:

• spec.document.upserted
• spec.document.deleted
• spec.span.created
• spec.comment.created
• spec.comment.action_requested
• consumer.registered
• consumer.updated
• agent.packet.created
• agent.request.created
• agent.request.executing
• agent.request.executed
• agent.request.failed
• agent.request.blocked
• agent.request.ignored

Authority values:

• human.file: direct edit to a Markdown spec file.
• human.ui: direct edit through the front end.
• importer.sync: materialization from filesystem into database.
• agent.proposal: agent-authored suggested change.
• agent.applied: accepted agent change written back into the source spec.
• charter.agent: agent request lifecycle activity.
• charter.system: system classification, packet construction, or queue transition.

A project event should carry source pointers: document id, span id, comment id, work item id, request id, source Jazz row id, and source field/path when available.

WorkItem #

Mutable CoMap representing agent-consumable work derived from a project event.

Fields:

• id: stable work item id, usually derived from source event id.
• kind: spec-change, span-action, comment-action, agent-request, or manual.
• status: queued, claimed, running, done, ignored, failed, or blocked.
• eventId: source event feed entry.
• documentId / path / title: affected spec document.
• spanId / commentId when applicable.
• matchedConsumerIds: consumers eligible to handle the work.
• attachedDocumentIds: spec documents supplied as agent context.
• sourceJazzRowId / sourceField: Jazz provenance pointer when available.
• claimedBy / claimedAt: worker claim metadata.
• requestId: linked AgentRequest once running.
• resultText: optional completion summary.

AgentConsumer #

Database-registered consumer specification.

Fields:

• id.
• name.
• status: active, paused, archived.
• runnerKind: Letta, Codex, Claude Code, script, CI, custom.
• runnerCommand: optional default command or adapter command.
• runnerConfigJson: non-secret runner configuration.
• eventTypes / eventTypesJson: subscribed event types.
• documentSelectors / documentSelectorsJson: subscribed document ids, folders, tags, or query selectors.
• promptDocumentIds / promptDocumentIdsJson: prompt/spec documents composing behavior.
• defaultContextDocumentIds / defaultContextDocumentIdsJson.
• cursorJson: last seen event ids or timestamps.
• createdAt / updatedAt.

Secrets do not belong in the consumer row. Store references to secret names or host-side config, not credential material.

Consumer registration is a write operation with a bounded response shape. Charter should return the created or updated AgentConsumer, the registration/update event id, any matched queued work item ids, and a match event count. Full snapshots belong to explicit inspection commands or read endpoints like charter consumers, GET /api/project, GET /api/consumers, and GET /api/work-items.

When a consumer is registered after work already exists, Charter can rematch existing queued work by re-evaluating each queued work item's source event against that consumer's subscriptions. Rematching updates matchedConsumerIds; it does not recreate the source event or duplicate the work item.

WorkPacket #

The exact packet handed to a consumer run.

Fields:

• id.
• consumerId.
• requestId when created for execution.
• workItemIds.
• eventIds.
• documentVersionIds.
• affectedDocumentIds.
• promptDocumentIds.
• attachedDocumentIds.
• documentVersionIds: document id to content hash/version id for attached context.
• prompt: rendered prompt for simple runner compatibility.
• promptSha256.
• outputContract.
• status: planned, executing, executed, failed, blocked, or ignored.
• raw output fields and result text after execution.
• createdAt / updatedAt.

Packets make runs inspectable and reproducible. The packet is not the whole world; it is the bounded work context Charter chose to hand over.

AgentRequest #

Database-backed request for an implementation agent or other consumer runner.

Fields:

• id: stable request identity derived from the packet or prompt hash.
• status: planned, executing, executed, failed, or blocked.
• createdAt / updatedAt: lifecycle timestamps.
• requestedBy: request authority, initially charter.agent.
• consumerId: registered consumer handling the request.
• packetId: linked packet.
• command: optional runner command used for execution.
• changeIds: spec document ids that changed.
• workItemIds: durable work items attached to this request.
• attachedDocumentIds: spec document ids attached as request context.
• prompt: rendered runner prompt for simple runner compatibility.
• promptSha256: prompt content hash.
• resultText: optional runner summary.
• exitCode: optional runner exit code.

Agent context is document/span/comment attachment plus prompt documents. If an agent needs more durable context, attach or create spec documents rather than writing to a separate memory table.

Agent output capture #

AgentRequest records should store both structured completion and raw execution output.

Structured fields:

• status: planned, executing, executed, failed, or blocked.
• reportStatus: done, failed, blocked, ignored, or seen when explicitly reported by the consumer.
• resultText: human-readable completion report.
• reportedAt: explicit report timestamp.

Raw audit fields:

• stdoutText
• stderrText
• outputText
• exitCode

WorkItem records mirror the actionable status and report text so queue consumers do not need to inspect the parent request for common routing decisions.

AgentActivity #

Agent activity is optional at first, but the model should have a place for it.

Examples:

• consumer saw event and chose no-op.
• consumer constructed packet.
• consumer requested more context.
• consumer failed while resolving a span.
• consumer produced a proposal.
• selected reasoning trace or diagnostic was recorded.

Activity records can enter the project event stream when they are meaningful to other consumers. They should not become a dumping ground for every token unless the UI has a reason to expose that much machine weather.