Bundle Format v2

Status: Implemented — v2 is the published contract at public/schema/project-bundle.json, generated from the canonical zod source in packages/schema (toolchain.md). Implemented behavior is documented in data-layer.md. This document remains the normative contract. The key words MUST, MUST NOT, SHOULD, and MAY are to be interpreted as in RFC 2119.

Overview

A ProjectBundle is the interchange unit of the arkaik format: one JSON document carrying a project, its nodes, and its edges. Version 2 makes the format versioned and extensible while keeping every v1 bundle valid.

interface ProjectBundle {
  schema_version?: number;   // v2: contract version; absent means 1
  project: Project;
  nodes: Node[];
  edges: Edge[];
  journal?: JournalEvent[];  // v2: embedded interchange projection only — see spec/journal.md
}

Node, Edge, Project, playlist, platform, and status semantics are unchanged from v1 — see graph-model.md and the type definitions in lib/data/types.ts. v2 is strictly additive.

Schema Versioning

Why v2 requires an explicit bump even though it is additive: the published v1 JSON Schema declares additionalProperties: false on the bundle root and on Project. Any bundle carrying schema_version, journal, or project.version is non-conformant to v1 by construction. The v2 JSON Schema (generated from the canonical source, see toolchain.md) relaxes this to "unknown fields are allowed and preserved."

v3: status vocabulary overhaul (discovery added; prioritized/blocked removed; blocked_by metadata; old backlog → idea). Migration stamps schema_version: 3.

Known consumer defect to fix before v2 ships: rewriteBundleProjectId (lib/utils/export.ts) reconstructs imported bundles as { project, nodes, edges } and silently drops any other top-level key when an imported project's ID collides locally. All import paths MUST round-trip unknown fields.

Project Additions

interface Project {
  // ... unchanged v1 fields (id, title, description?, root_node_id?, metadata?, timestamps)
  version?: string;          // v2, Level 1: current version label, e.g. "1.4.0" or "2026-07"
}

project.version is the current version label of the mapped product (free-form string; semver recommended, not required). Version history lives in the journal as release.tagged events — a Level 1 bundle carries only the label.

Products

A project describes a family of apps sharing one graph — an end-user app, a web-only back office, a public API — not a single product with three platforms. A product names one app in that family and the platforms it can ship on:

interface ProductDefinition extends Record<string, unknown> {
  id: string;                // kebab-case, unique within the project
  title: string;
  description?: string;
  platforms: PlatformId[];   // the menu this product may ship on; MAY be []
  root_node_id?: string;     // this product's journey anchor
}

Definitions live at project.metadata.products: ProductDefinition[], following the project.metadata.maps precedent (maps.md § Storage) exactly: a purely additive optional field in an already-catchall object, so it requires no schema_version bump, and unknown fields on a definition are preserved and ignored.

A definition declares a product when its id is a non-blank string; resolveProducts drops everything else, and a dropped entry declares nothing. The two dropped shapes are reported in different places, by design. An id that is missing or not a string is a shape fault — id is required, so the parser rejects such a bundle and validateBundle() stays silent rather than repeating the rejection. An id that parses as a string but is blank or whitespace-only is well-shaped and reaches the validator, which reports it as product-invalid-id (§ Validation below). Duplicate ids resolve first-wins, so every projection stays deterministic on a bundle the validator has already warned about.

Membership

Shared substrate is the norm, so the system layer never claims a product of its own. Derived membership walks outward from every node that stores membership along calls / displays / queries edges, following each edge in its stored direction and hopping only into data-model and api-endpoint targets; every node so reached is used by that product. (In practice the walk starts at flows and views: edge-semantics admits none of those three edge types out of an acceptance, so an acceptance seeds nothing.) productsUsingNode (@arkaik/schema) is a lookup into an index built once per snapshot, never a per-card traversal.

Both restrictions are load-bearing. Following each edge in its stored direction keeps the walk pointed down into the system layer: the Journey renderer projects a calls edge sourced at an api-endpoint as a View's inbound/read affordance (graph-model.md § Edge Types), and a direction-blind walk would follow exactly that shape back up into another product's views. And any undirected formulation is all-pairs within a connected component, which would make a data model that only Admin touches report as used by the end-user app merely because the two products share some other model.

A node reached by no consumer belongs to no product. Consumers scoping by product MUST still show such orphans under every scope rather than hiding them — burying the nodes that most need attention is the failure mode this format exists to end (maps.md § Orphans).

Platforms

node.platforms stays authoritative; every existing projection keeps reading it unchanged. A product's platforms is a menu, and a node's list SHOULD be a subset of its product's. A violation is a warning, never an error, because the menu is edited independently of the node: narrowing Admin from [web, ios] to [web] is a product decision, and it MUST NOT fail CI on nodes nobody touched.

Readers intersect rather than trust: effectiveNodePlatforms(node, product) returns node.platforms ∩ product.platforms in PLATFORM_IDS order, so an out-of-menu platform drops out of the display instead of corrupting it — which is exactly why an error would buy no safety the intersection does not already provide.

platforms: [] means availability is not a tracked dimension for this product (a CLI, a public API). Such a product carries a single lifecycle status: the intersection above is empty for every node in it, so there is no per-platform breakdown to render.

The degenerate case

A bundle with no products key behaves exactly as it did before products existed: one implicit product spanning PLATFORM_IDS, every node in it, no warnings, and no migration. productPlatforms(project, productId) states the whole rule — a project declaring no products returns PLATFORM_IDS; null (All products) returns the union of every declared menu; a product id returns that product's own menu; and an unknown id resolves like null, because a stale scope MUST degrade rather than throw.

MapDefinition.product scopes a stored map to one product (maps.md § MapDefinition), so "the therapist app map" is data rather than a parallel mechanism.

Validation

Product findings are reported by validateBundle() at warning severity only, matching stored maps (maps.md § Validation): a stale definition or a dangling membership must never fail an import or a CI gate. validateBundle().valid stays true for every finding below.

Four of the eight are ungated, for two different reasons. product-duplicate-id and product-invalid-id read the stored array itself, so they fire wherever project.metadata.products exists at all — which is precisely what keeps a blank id visible instead of swallowing it. product-unknown-reference and product-membership-wrong-species are statements about a single node's own stored field, true or false regardless of project state — the same posture that leaves gherkin-species and values-species ungated. The motivating case for the latter pair is the author who writes metadata.product on a handful of nodes before adding project.metadata.products; gating them would make exactly that mistake invisible.

The other four require at least one declared product, because "out of menu", "unassigned", and "spans two products" say nothing until something is declared.

The invariant that holds either way, and that the test suite asserts across every species: a bundle with no products key and no metadata.product on any node raises zero product findings.

Absent membership is a triage state, not "applies everywhere" — an unassigned flow, view, or anchorless acceptance appears under "All products" only, so the warnings above read as an inbox rather than as noise duplicated into every scope. Shape faults (products not an array, a definition missing title) stay where they belong, in the parser and the JSON Schema.

References

v2 adds typed external references to nodes, under metadata.refs (placed in NodeMetadata alongside platformStatuses and friends):

interface Ref {
  id: string;                // unique within the node, kebab-case, e.g. "gh-142"
  type: "figma" | "github-issue" | "gitlab-issue" | "linear-issue"
      | "github-pr" | "gitlab-mr" | "url";
  url: string;               // canonical external URL
  title?: string;            // display label
  external_status?: string;  // mirrored external state, verbatim (e.g. "open", "merged", "In Progress")
  status_mapped?: StatusId;  // optional mapping of external_status into the arkaik lifecycle
  platform?: PlatformId;     // optional scoping to one platform variant
  synced_at?: string;        // ISO 8601 — when external_status was last mirrored
}

Asset Values

Anywhere the format carries an asset (today: metadata.platformScreenshots, a per-platform map), the value MUST be one of three forms:

Consumers that cannot resolve a form (the hosted app receiving a relative path, for instance) MUST degrade to a placeholder, never fail the import. arkaik pack converts between forms (inline or upload) when producing a self-contained interchange file. Journal events MUST NOT embed asset payloads.

Size-bomb guidance: a data: value SHOULD stay under 2MB decoded — the same cap the app's own screenshot upload enforces. validateBundle() (@arkaik/schema) emits a screenshot-data-uri-size warning (never an error) above that threshold: data URIs are a legitimate legacy form and MUST NOT be rejected on size alone, only flagged so producers can migrate to a hosted or relative-path form.

Acceptance Nodes

An acceptance node (id prefix AC-) is a testable promise: title is the What, metadata.gherkin holds exactly one Given/When/Then scenario (the How), metadata.values holds 1..n elements of the core value enum (the Why — Bain B2C pyramid, see the generated JSON Schema Value enum). Per-platform status uses the same metadata.platformStatuses mechanic as views; platforms lists the platforms where the behavior is expected ("availability").

covers edges (acceptance → view | flow) anchor the promise to surfaces. Zero covers edges is legal, and it is intake, not "applies everywhere": an idea filed before the flows and views exist, carrying metadata.product from day one and waiting to be decomposed (§ Products). It is anchorless, and the app calls it that. Stored per-platform status lives on acceptances; covered views compute theirs (validator: missing gherkin/values on an acceptance are warnings; unknown value ids are errors; gherkin/values on other species are warnings).

Decision Nodes

A decision node (id prefix DEC-) is an ADR-style record: title + description hold the Decision/What, metadata.context (markdown) holds the Context/Why, metadata.consequences (markdown) holds the Consequences/How. Four metadata fields are meaningful on decision nodes only:

interface NodeMetadata {
  // ... unchanged fields
  decision_status?: DecisionStatus;  // decision nodes only — see below
  context?: string;                  // decision nodes only — markdown, the Why
  consequences?: string;             // decision nodes only — markdown, the How
  decided_at?: string;               // decision nodes only — ISO 8601 date
}

decided_at is optional and exists for historical backfill: a bulk-imported node.created journal event carries the backfill run's timestamp, not the day the decision was actually made, so decided_at is the only place the real date lives.

metadata.decision_status is its own enum, distinct from the node lifecycle status (the metadata.platformStatuses precedent, not a species-specific status vocabulary):

type DecisionStatus =
  | "proposed" | "approved" | "enacted"
  | "rejected" | "deprecated" | "superseded";  // last three are terminal

The node's global status is kept in sync at write time via lifecycleStatusForDecision (@arkaik/schema), so every status-driven surface keeps working without branching by species:

validateBundle() cross-checks the mapping as a warning (decision-lifecycle-mismatch), never an error — a hand-edited bundle must not brick on a stale sync. decision_status present on a non-decision node is also a warning (decision-status-wrong-species); an unknown decision_status value is rejected at the schema-parse boundary, same posture as an unknown lifecycle status.

Three edge types are decision-only:

generates and impacts are deliberately disjoint: an acceptance is generated by a decision, never merely impacted, so impacts does not admit an acceptance target — consumers MUST NOT infer an edge's meaning from its endpoints.

Decisions legitimately carry an empty platforms array — they are platform-agnostic records, not something that ships. platforms-non-empty exempts the decision species for exactly this reason, the same way the Products section's rules gate on species.

All of the above is additive: no schema_version bump. Every field is optional metadata, every enum member and edge type is new vocabulary, and the one new journal event (decision.status_changed, journal.md § Event Vocabulary) follows the forward-compatibility rule in the Event Envelope — this is the same posture as the Products addition earlier in this document. Old bundles parse unchanged; a bundle with no decision nodes renders empty states.

Identifier Conventions

IDs are deterministic and human-readable. This subsumes and canonicalizes the rules in docs/arkaik-skill/references/schema.md.

Canonical Serialization

So that bundles diff and merge cleanly in git, writers SHOULD emit canonical form; arkaik validate --fix-format (toolchain) normalizes it:

• UTF-8, LF line endings, 2-space indentation, trailing newline
• Top-level key order: schema_version, project, nodes, edges, journal
• nodes and edges sorted by id (codepoint ascending)
• Object keys in the field order defined by the schema

Canonical form localizes concurrent edits to the same region only when they genuinely touch the same entity. It does not make snapshot merges conflict-free — concurrent edits to the same node still conflict, by design (see the authority model in journal.md).

Conformance Levels

Every consumer MUST accept all three levels. Producers choose the level that fits their workflow.