arkaik 0.1.0

package/dist/assets/skill/references/schema.md

@@ -0,0 +1,368 @@
+# Arkaik ProjectBundle Schema Reference
+
+## Table of Contents
+
+1. [Types](#types)
+2. [Playlist Entries](#playlist-entries)
+3. [Edge Type Semantics](#edge-type-semantics)
+4. [ID Conventions](#id-conventions)
+5. [Validation Checklist](#validation-checklist)
+
+---
+
+## Types
+
+The canonical shape of a ProjectBundle, generated from the `@arkaik/schema` zod
+definitions (`docs/spec/toolchain.md` § @arkaik/schema). Do not hand-edit the
+block below — run `npm run generate`.
+
+<!-- GENERATED:SCHEMA:START -->
+```typescript
+type SpeciesId = "flow" | "view" | "data-model" | "api-endpoint" | "acceptance";
+type StatusId = "idea" | "backlog" | "prioritized" | "development" | "releasing" | "live" | "archived" | "blocked";
+type PlatformId = "web" | "ios" | "android";
+type EdgeTypeId = "composes" | "calls" | "displays" | "queries" | "covers";
+
+type PlaylistEntry =
+  | { type: "view"; view_id: string }
+  | { type: "flow"; flow_id: string }
+  | { type: "condition"; label: string; if_true: PlaylistEntry[]; if_false: PlaylistEntry[] }
+  | { type: "junction"; label: string; cases: JunctionCase[] };
+
+interface JunctionCase {
+  label: string;
+  entries: PlaylistEntry[];
+}
+
+interface FlowPlaylist {
+  entries: PlaylistEntry[];
+}
+
+type PlatformNotesMap = Partial<Record<PlatformId, string>>;
+type PlatformStatusMap = Partial<Record<PlatformId, StatusId>>;
+type PlatformScreenshotsMap = Partial<Record<PlatformId, string>>;
+
+type RefType =
+  | "figma"
+  | "github-issue"
+  | "gitlab-issue"
+  | "linear-issue"
+  | "github-pr"
+  | "gitlab-mr"
+  | "url";
+
+interface Ref {
+  /** Unique within the node, kebab-case (e.g. "gh-142"). */
+  id: string;
+  /** One of {@link RefType}; unrecognized values are preserved and render as generic links. */
+  type: RefType | (string & {});
+  /** Canonical external URL. */
+  url: string;
+  /** Display label. */
+  title?: string;
+  /** Mirrored external state, verbatim (e.g. "open", "merged", "In Progress"). */
+  external_status?: string;
+  /** Optional mapping of external_status into the arkaik lifecycle. Advisory display data — never mutates node.status. */
+  status_mapped?: StatusId;
+  /** Optional scoping to one platform variant. */
+  platform?: PlatformId;
+  /** ISO 8601 — when external_status was last mirrored. */
+  synced_at?: string;
+}
+
+interface NodeMetadata extends Record<string, unknown> {
+  stage?: string;
+  playlist?: FlowPlaylist;
+  platformNotes?: PlatformNotesMap;
+  platformStatuses?: PlatformStatusMap;
+  platformScreenshots?: PlatformScreenshotsMap;
+  refs?: Ref[];
+  /** Acceptance nodes: one Given/When/Then scenario — the How (spec §3.1). */
+  gherkin?: string;
+  /** Acceptance nodes: value elements served — the Why (spec §3.2). */
+  values?: ValueId[];
+}
+
+interface Node {
+  id: string;
+  project_id: string;
+  species: SpeciesId;
+  title: string;
+  description?: string;
+  status: StatusId;
+  platforms: PlatformId[];
+  metadata?: NodeMetadata;
+}
+
+interface Edge {
+  id: string;
+  project_id: string;
+  source_id: string;
+  target_id: string;
+  edge_type: EdgeTypeId;
+  metadata?: Record<string, unknown>;
+}
+
+interface ProjectMetadata extends Record<string, unknown> {
+  view_card_variant?: "compact" | "large";
+  maps?: MapDefinition[];
+}
+
+interface Project {
+  id: string;
+  title: string;
+  description?: string;
+  /** v2: current version label, free-form (semver recommended, not required), e.g. "1.4.0" or "2026-07". Version history lives in the journal. */
+  version?: string;
+  /** Optional node id used as the primary canvas anchor/root. */
+  root_node_id?: string;
+  /** Optional project-level UI settings and preferences. */
+  metadata?: ProjectMetadata;
+  /** ISO 8601 timestamp, e.g. "2024-01-01T00:00:00.000Z" */
+  created_at: string;
+  /** ISO 8601 timestamp, e.g. "2024-01-01T00:00:00.000Z" */
+  updated_at: string;
+  /** ISO 8601 timestamp when archived; null/undefined means active. */
+  archived_at?: string | null;
+}
+
+interface JournalEvent extends Record<string, unknown> {
+  /** ULID — sortable, collision-free without coordination. */
+  id: string;
+  /** ISO 8601 timestamp. */
+  ts: string;
+  /** Who/what wrote it: "alexis", "claude-code", "arkaik-sync", "ci". */
+  actor?: string;
+  /** Event type — the v1 vocabulary, or an unknown forward-compatible value. */
+  type: string;
+  /** Reserved per-event payload version, for the day a payload shape changes. */
+  v?: number;
+}
+
+interface NodeCreatedEvent extends JournalEvent {
+  type: "node.created";
+  node_id: string;
+  species: SpeciesId;
+  title: string;
+}
+
+interface NodeUpdatedEvent extends JournalEvent {
+  type: "node.updated";
+  node_id: string;
+  fields: string[];
+  from?: unknown;
+  to?: unknown;
+}
+
+interface NodeStatusChangedEvent extends JournalEvent {
+  type: "node.status_changed";
+  node_id: string;
+  from: StatusId;
+  to: StatusId;
+  platform?: PlatformId;
+}
+
+interface NodeDeletedEvent extends JournalEvent {
+  type: "node.deleted";
+  node_id: string;
+}
+
+interface EdgeAddedEvent extends JournalEvent {
+  type: "edge.added";
+  edge_id: string;
+  source_id: string;
+  target_id: string;
+  edge_type: EdgeTypeId;
+}
+
+interface EdgeRemovedEvent extends JournalEvent {
+  type: "edge.removed";
+  edge_id: string;
+}
+
+interface ReleaseTaggedEvent extends JournalEvent {
+  type: "release.tagged";
+  version: string;
+  notes?: string;
+  platform?: PlatformId;
+}
+
+interface IdeaProposedEvent extends JournalEvent {
+  type: "idea.proposed";
+  title: string;
+  description?: string;
+  node_id?: string;
+}
+
+interface RequestFiledEvent extends JournalEvent {
+  type: "request.filed";
+  title: string;
+  description?: string;
+  source?: string;
+  node_id?: string;
+}
+
+interface RefAddedEvent extends JournalEvent {
+  type: "ref.added";
+  node_id: string;
+  ref_id: string;
+  ref_type: string;
+  url: string;
+}
+
+interface RefRemovedEvent extends JournalEvent {
+  type: "ref.removed";
+  node_id: string;
+  ref_id: string;
+}
+
+interface RefStatusChangedEvent extends JournalEvent {
+  type: "ref.status_changed";
+  node_id: string;
+  ref_id: string;
+  from?: string;
+  to: string;
+  synced_at: string;
+}
+
+type KnownJournalEvent =
+  | NodeCreatedEvent
+  | NodeUpdatedEvent
+  | NodeStatusChangedEvent
+  | NodeDeletedEvent
+  | EdgeAddedEvent
+  | EdgeRemovedEvent
+  | ReleaseTaggedEvent
+  | IdeaProposedEvent
+  | RequestFiledEvent
+  | RefAddedEvent
+  | RefRemovedEvent
+  | RefStatusChangedEvent;
+
+interface ProjectBundle {
+  /** Bundle Format contract version (docs/spec/bundle-format.md § Schema Versioning). Absent MUST be treated as 1. */
+  schema_version?: number;
+  project: Project;
+  nodes: Node[];
+  edges: Edge[];
+  /** Optional embedded journal — the interchange projection (Level 2). Canonical storage is the JSONL sidecar; see docs/spec/journal.md. */
+  journal?: JournalEvent[];
+}
+```
+<!-- GENERATED:SCHEMA:END -->
+
+---
+
+## Playlist Entries
+
+Flows orchestrate views through an ordered playlist (`PlaylistEntry`, above).
+Each entry is one of `view`, `flow`, `condition`, or `junction`.
+
+**Condition** is a binary branch (yes/no question). The `label` is a question
+(e.g., "Email verified?"), and `if_true` / `if_false` contain the entries for
+each branch. Either branch can be empty `[]` to mean "skip."
+
+**Junction** is a multi-way branch. The `label` is a question (e.g., "What
+action?"), and `cases` is an array of labeled branches, each with its own
+entries.
+
+Every `view_id` and `flow_id` in playlist entries must reference node IDs that
+exist in the bundle's `nodes` array.
+
+---
+
+## Edge Type Semantics
+
+| Edge type | Valid source → target | Meaning |
+|---|---|---|
+| `composes` | flow → view | Flow contains this view in its playlist |
+| `composes` | flow → flow | Flow contains this sub-flow in its playlist |
+| `composes` | view → flow | View triggers/navigates to this flow |
+| `composes` | view → view | View contains or navigates to this view |
+| `calls` | view → api-endpoint | View calls this API |
+| `calls` | flow → api-endpoint | Flow calls this API |
+| `calls` | api-endpoint → api-endpoint | Endpoint calls another (internal or third-party) API — e.g. a server action / BFF route fanning out to external APIs |
+| `displays` | view → data-model | View displays data from this model |
+| `queries` | api-endpoint → data-model | API reads or writes this model |
+
+Any other source → target combination for a given edge type is invalid.
+
+---
+
+## ID Conventions
+
+| Species | Prefix | Example |
+|---|---|---|
+| flow | `F-` | `F-record-pebble` |
+| view | `V-` | `V-pebble-detail` |
+| data-model | `DM-` | `DM-emotion-pearl` |
+| api-endpoint | `API-` | `API-create-pebble` |
+
+After the prefix, use lowercase kebab-case. Keep IDs short but meaningful —
+they appear in the Arkaik UI.
+
+Edge IDs: `e-{source_id}-{target_id}` (e.g., `e-V-home-F-onboarding`).
+
+### IDs must be globally unique
+
+A node ID identifies exactly one node. The graph layout (elkjs) and the canvas
+(React Flow) both key nodes by ID, so **two nodes sharing an ID break the entire
+graph render**, and any edge pointing at that ID silently resolves to whichever
+node was defined last.
+
+Derive IDs **deterministically from the title**, then check the result against
+every existing ID before adding the node. If a derived ID already exists but the
+node is genuinely different, disambiguate the ID (do not reuse it).
+
+### Data-model IDs: concepts vs. physical tables
+
+`DM-` nodes come in two flavors that must derive **distinct** IDs so they never
+collide:
+
+| Flavor | Title style | ID derivation | Examples |
+|---|---|---|---|
+| **Conceptual model** | Capitalized noun ("Pebble", "Bounce", "Soul") | `DM-<concept>` (singular) | `DM-pebble`, `DM-bounce`, `DM-soul` |
+| **Physical table / view** | Exact DB identifier, lowercase snake_case (`bounces`, `karma_events`, `v_analytics_kpi_daily`) | `DM-<table_name>` with underscores → hyphens, **preserving pluralisation** | `DM-bounces`, `DM-karma-events`, `DM-v-analytics-kpi-daily` |
+
+The concept **Bounce** (`DM-bounce`) and the table **bounces** (`DM-bounces`) are
+different nodes — kebab-casing both to `DM-bounce` is the collision that broke the
+map. When a concept and its backing table both exist, keep the concept singular
+and the table plural/exact so their IDs differ.
+
+### Titles
+
+- **Views, flows, API endpoints, conceptual data-models:** 2–5 words, descriptive
+  and capitalized (e.g., "User Profile", "Record Pebble", "GET /bounce", "Pebble").
+- **Physical table / view data-models:** the exact database identifier verbatim
+  (e.g., `bounces`, `karma_events`, `v_analytics_kpi_daily`) — do not prettify.
+
+Every node's `title` must be present and non-empty regardless of species.
+
+---
+
+## Validation Checklist
+
+Before saving any changes, verify:
+
+1. All node IDs are unique across the whole bundle (no two nodes share an ID)
+2. All node IDs have the correct species prefix
+3. Every node has a non-empty `title`
+4. All `node.project_id` values match `project.id`
+5. All `edge.source_id` and `edge.target_id` reference existing node IDs
+6. All `edge.project_id` values match `project.id`
+7. Every edge ID follows `e-{source_id}-{target_id}` (update it when you repoint an edge)
+8. No duplicate edge relationships (same source, target, and type)
+9. `project.root_node_id` references an existing node
+10. All `view_id` / `flow_id` in playlists reference existing node IDs
+11. Every view/flow referenced in a playlist has a corresponding `composes` edge
+12. No playlist cycles (a flow does not contain itself directly or indirectly)
+13. All flow nodes have `metadata.playlist` with at least one entry
+14. All `platforms` arrays have at least one value
+15. Any `metadata.stage` is one of `beta` / `monitoring` / `deprecated`
+16. Any `metadata.platformStatuses` / `platformNotes` use valid platforms (and statuses); `platformStatuses` keys are a subset of `node.platforms`
+17. `project.metadata.view_card_variant`, if set, is `compact` or `large` (import **rejects** other values)
+18. Edge types follow the valid source → target patterns
+19. `created_at` / `updated_at` are valid ISO 8601 timestamps; `updated_at` is current
+
+The bundled validator (`scripts/validate-bundle.js`) enforces every item above.
+Treat a non-zero exit code as a hard stop — do not commit a bundle it rejects.

package/dist/assets/skill/references/values.md

@@ -0,0 +1,47 @@
+# Value Elements — Bain B2C Pyramid (30)
+
+One-line definitions for `metadata.values`. Assign 1–3 per acceptance; prefer
+the most specific element; when torn between tiers, pick the higher tier only
+if the acceptance genuinely operates there.
+
+## Functional
+
+- `saves-time` — completes the user's task in less time.
+- `simplifies` — reduces steps, choices, or cognitive load.
+- `makes-money` — helps the user earn.
+- `reduces-risk` — protects against loss, error, or uncertainty.
+- `organizes` — brings order to the user's things or life.
+- `integrates` — ties different tools/parts of life together.
+- `connects` — brings the user together with other people.
+- `reduces-effort` — same outcome, less work.
+- `avoids-hassles` — prevents friction and annoyance before it happens.
+- `reduces-cost` — saves the user money.
+- `quality` — superior craft or performance the user can feel.
+- `variety` — meaningful choice and breadth.
+- `sensory-appeal` — looks, sounds, or feels good in the moment.
+- `informs` — tells the user something they want to know.
+
+## Emotional
+
+- `reduces-anxiety` — calms; makes the user feel safe.
+- `rewards-me` — tangible perks for engagement.
+- `nostalgia` — positive memory of the past.
+- `design-aesthetics` — beauty as an experienced value, beyond function.
+- `badge-value` — signals identity or status to others.
+- `wellness` — improves physical or mental well-being.
+- `therapeutic-value` — actively supports emotional processing or healing.
+- `fun-entertainment` — enjoyable, playful, delightful.
+- `attractiveness` — makes the user feel attractive.
+- `provides-access` — grants entry to something otherwise out of reach.
+
+## Life-changing
+
+- `provides-hope` — reason to believe things can improve.
+- `self-actualization` — helps the user become who they want to be.
+- `motivation` — energizes the user toward their goals.
+- `heirloom` — something worth passing on across time.
+- `affiliation-belonging` — makes the user part of a group that matters.
+
+## Social impact
+
+- `self-transcendence` — helps beyond the user themselves.

package/dist/assets/skill/scripts/validate-bundle.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Arkaik ProjectBundle Validator — GENERATED, DO NOT EDIT BY HAND.
+ * Built via `npm run generate` from packages/schema/src (the canonical zod
+ * definitions, docs/spec/toolchain.md § @arkaik/schema). Zero dependencies —
+ * runnable with nothing but Node.
+ *
+ * Validates a bundle.json file against the Arkaik schema rules.
+ * Exit code 0 = valid, 1 = errors found.
+ *
+ * Usage: node validate-bundle.js <path-to-bundle.json>
+ */
+"use strict";var P=require("node:fs"),B=require("node:path");var G=["flow","view","data-model","api-endpoint","acceptance"],C=["idea","backlog","prioritized","development","releasing","live","archived","blocked"],q=["web","ios","android"],K=["composes","calls","displays","queries","covers"];var Q=["saves-time","simplifies","makes-money","reduces-risk","organizes","integrates","connects","reduces-effort","avoids-hassles","reduces-cost","quality","variety","sensory-appeal","informs","reduces-anxiety","rewards-me","nostalgia","design-aesthetics","badge-value","wellness","therapeutic-value","fun-entertainment","attractiveness","provides-access","provides-hope","self-actualization","motivation","heirloom","affiliation-belonging","self-transcendence"];var Z={flow:"F-",view:"V-","data-model":"DM-","api-endpoint":"API-",acceptance:"AC-"};function de(f){let a=e=>typeof e=="string"?e:"";return[...f].sort((e,r)=>{let $=a(e.ts),v=a(r.ts);if($<v)return-1;if($>v)return 1;let p=a(e.id),y=a(r.id);return p<y?-1:p>y?1:0})}function ee(f){let a=[],e=[];return f.split(/\r?\n/).forEach(($,v)=>{let p=v+1;if($.trim()==="")return;let y;try{y=JSON.parse($)}catch(h){e.push({line:p,rule:"journal-line-parse",message:`Line ${p}: not valid JSON \u2014 ${h.message}`,severity:"error"});return}if(typeof y!="object"||y===null||Array.isArray(y)){e.push({line:p,rule:"journal-line-shape",message:`Line ${p}: each journal line must be a single JSON event object.`,severity:"error"});return}let _=y,E=[];if(typeof _.id!="string"&&E.push("id"),typeof _.ts!="string"&&E.push("ts"),typeof _.type!="string"&&E.push("type"),E.length>0){e.push({line:p,rule:"journal-line-shape",message:`Line ${p}: event is missing required envelope field(s): ${E.join(", ")}.`,severity:"error"});return}a.push(_)}),{events:a,findings:e}}var ce={"node.updated":["node_id"],"node.status_changed":["node_id"],"node.deleted":["node_id"],"edge.added":["source_id","target_id"],"ref.added":["node_id"],"ref.removed":["node_id"],"ref.status_changed":["node_id"],"idea.proposed":["node_id"],"request.filed":["node_id"]};function te(f){let a=[],e=f.journal;if(e===void 0)return a;if(!Array.isArray(e))return a.push({path:"journal",rule:"journal-shape",message:"journal must be an array of events when present.",severity:"error"}),a;if(e.length===0)return a;let r=o=>typeof o=="string"?o:void 0,$=Array.isArray(f.nodes)?f.nodes:[],v=Array.isArray(f.edges)?f.edges:[],p=new Map;for(let o of $){let d=r(o?.id);d!==void 0&&p.set(d,o.status)}let y=new Set;for(let o of v){let d=r(o?.id);d!==void 0&&y.add(d)}let _=[];e.forEach((o,d)=>{let w=`journal[${d}]`;if(typeof o!="object"||o===null||Array.isArray(o)){a.push({path:w,rule:"journal-event-shape",message:`journal[${d}]: each event must be a JSON object.`,severity:"error"});return}let S=o,j=[];if(r(S.id)===void 0&&j.push("id"),r(S.ts)===void 0&&j.push("ts"),r(S.type)===void 0&&j.push("type"),j.length>0){a.push({path:w,rule:"journal-event-envelope",message:`journal[${d}]: event is missing required envelope field(s): ${j.join(", ")}.`,severity:"error"});return}_.push({ev:S,index:d})});let E=new Set(p.keys()),h=new Set(y);for(let{ev:o}of _)if(o.type==="node.created"){let d=r(o.node_id);d&&E.add(d)}else if(o.type==="edge.added"){let d=r(o.edge_id);d&&h.add(d)}let R=de(_.map(o=>o.ev)),I=new Set,b=new Map;for(let o of R)if(o.type==="node.created"){let d=r(o.node_id);d&&I.add(d)}else if(o.type==="node.status_changed"){let d=r(o.node_id);if(d&&o.platform===void 0){let w=r(o.to);w!==void 0&&b.set(d,w)}}for(let{ev:o,index:d}of _){let w=ce[o.type];if(w)for(let S of w){let j=r(o[S]);j!==void 0&&!E.has(j)&&a.push({path:`journal[${d}].${S}`,rule:"journal-dangling-node-ref",message:`journal[${d}] (${o.type}): references node "${j}" that never existed in the snapshot or journal.`,severity:"error"})}if(o.type==="edge.removed"){let S=r(o.edge_id);S!==void 0&&!h.has(S)&&a.push({path:`journal[${d}].edge_id`,rule:"journal-dangling-edge-ref",message:`journal[${d}] (edge.removed): references edge "${S}" that never existed in the snapshot or journal.`,severity:"error"})}}for(let[o,d]of p){I.has(o)||a.push({path:"journal",rule:"journal-missing-node-created",message:`Node "${o}" is present in the snapshot but has no node.created event in the journal.`,severity:"error"});let w=b.get(o);w!==void 0&&w!==d&&a.push({path:"journal",rule:"journal-status-mismatch",message:`Node "${o}": journal's last node.status_changed.to "${w}" disagrees with snapshot status "${String(d)}".`,severity:"error"})}return a}var le=["journey","system"];function ne(f){return le.includes(f)}var pe=["beta","monitoring","deprecated"],se=["compact","large"],ie=2*1024*1024;function fe(f){let a=f.indexOf(",");if(a===-1)return 0;let e=f.slice(a+1),r=e.endsWith("==")?2:e.endsWith("=")?1:0;return Math.floor(e.length*3/4)-r}var ue={composes:[["flow","view"],["flow","flow"],["view","flow"],["view","view"]],calls:[["view","api-endpoint"],["flow","api-endpoint"],["api-endpoint","api-endpoint"]],displays:[["view","data-model"]],queries:[["api-endpoint","data-model"]],covers:[["acceptance","view"],["acceptance","flow"]]};function oe(f){return typeof f=="string"&&!Number.isNaN(Date.parse(f))}function re(f){let a=[],e=(s,u,n)=>a.push({path:s,rule:u,message:n,severity:"error"}),r=(s,u,n)=>a.push({path:s,rule:u,message:n,severity:"warning"}),$=()=>{let s=a.filter(n=>n.severity==="error"),u=a.filter(n=>n.severity==="warning");return{valid:s.length===0,findings:a,errors:s,warnings:u}};if(typeof f!="object"||f===null||Array.isArray(f))return e("","bundle-shape","Bundle must be an object with project, nodes, and edges."),$();let v=f,p=v.project,y=v.nodes,_=v.edges;if(!p||!y||!_)return e("","bundle-shape","Missing top-level keys (project, nodes, edges)."),$();if(!Array.isArray(y))return e("nodes","bundle-shape","nodes must be an array."),$();if(!Array.isArray(_))return e("edges","bundle-shape","edges must be an array."),$();let E=y,h=_,R=new Map,I=new Set;p.id||e("project.id","project-id-required","project.id is missing"),(typeof p.title!="string"||!p.title.trim())&&e("project.title","title-non-empty","project.title is missing or empty"),p.created_at||e("project.created_at","timestamp-required","project.created_at is missing"),p.updated_at||e("project.updated_at","timestamp-required","project.updated_at is missing"),p.created_at&&!oe(p.created_at)&&r("project.created_at","iso-timestamp","project.created_at is not a valid ISO 8601 timestamp"),p.updated_at&&!oe(p.updated_at)&&r("project.updated_at","iso-timestamp","project.updated_at is not a valid ISO 8601 timestamp");let b=p.metadata;b&&b.view_card_variant!==void 0&&!se.includes(b.view_card_variant)&&e("project.metadata.view_card_variant","view-card-variant",`project.metadata.view_card_variant must be one of ${se.join(", ")} (import rejects other values)`),E.forEach((s,u)=>{let n=`nodes[${u}]`,t=s.id;I.has(t)&&e(`${n}.id`,"duplicate-node-id",`Duplicate node ID: ${t}`),I.add(t),R.set(t,s),(typeof s.title!="string"||!s.title.trim())&&e(`${n}.title`,"title-non-empty",`Node ${t}: title is missing or empty`);let c=s.species,i=Z[c];i&&!(typeof t=="string"&&t.startsWith(i))&&e(`${n}.id`,"species-prefix",`Node ${t}: species "${c}" should have prefix "${i}"`),G.includes(c)||e(`${n}.species`,"valid-species",`Node ${t}: invalid species "${c}"`),s.project_id!==p.id&&e(`${n}.project_id`,"project-id-match",`Node ${t}: project_id "${s.project_id}" does not match project.id "${p.id}"`),C.includes(s.status)||e(`${n}.status`,"valid-status",`Node ${t}: invalid status "${s.status}"`);let m=s.platforms;if(!m||m.length===0)e(`${n}.platforms`,"platforms-non-empty",`Node ${t}: platforms array is empty or missing`);else for(let g of m)q.includes(g)||e(`${n}.platforms`,"valid-platform",`Node ${t}: invalid platform "${g}"`);let l=s.metadata||{};l.stage!==void 0&&!pe.includes(l.stage)&&e(`${n}.metadata.stage`,"valid-stage",`Node ${t}: invalid metadata.stage "${l.stage}"`);let x=l.platformNotes;if(x)for(let g of Object.keys(x))q.includes(g)||e(`${n}.metadata.platformNotes`,"valid-platform",`Node ${t}: platformNotes has invalid platform "${g}"`);let N=l.platformStatuses;if(N)for(let[g,A]of Object.entries(N))q.includes(g)?Array.isArray(m)&&!m.includes(g)&&r(`${n}.metadata.platformStatuses`,"platform-statuses-subset",`Node ${t}: platformStatuses covers platform "${g}" not in node.platforms`):e(`${n}.metadata.platformStatuses`,"valid-platform",`Node ${t}: platformStatuses has invalid platform "${g}"`),C.includes(A)||e(`${n}.metadata.platformStatuses`,"valid-status",`Node ${t}: platformStatuses has invalid status "${A}" for platform "${g}"`);let D=l.platformScreenshots;if(D){for(let[g,A]of Object.entries(D))if(typeof A=="string"&&A.startsWith("data:")){let O=fe(A);O>ie&&r(`${n}.metadata.platformScreenshots`,"screenshot-data-uri-size",`Node ${t}: platformScreenshots.${g} is a ${(O/(1024*1024)).toFixed(1)}MB data URI, above the ${ie/(1024*1024)}MB guidance (docs/spec/bundle-format.md \xA7 Asset Values) \u2014 consider a relative path or hosted URL instead`)}}let T=l.gherkin,M=l.values;if(c==="acceptance"?((typeof T!="string"||!T.trim())&&r(`${n}.metadata.gherkin`,"acceptance-gherkin-missing",`Acceptance ${t}: metadata.gherkin is missing or empty (one Given/When/Then scenario expected)`),(!Array.isArray(M)||M.length===0)&&r(`${n}.metadata.values`,"acceptance-values-missing",`Acceptance ${t}: metadata.values is missing or empty (assign 1-3 value elements)`)):(T!==void 0&&r(`${n}.metadata.gherkin`,"gherkin-species",`Node ${t}: metadata.gherkin is only meaningful on acceptance nodes`),M!==void 0&&r(`${n}.metadata.values`,"values-species",`Node ${t}: metadata.values is only meaningful on acceptance nodes`)),Array.isArray(M))for(let g of M)Q.includes(g)||e(`${n}.metadata.values`,"valid-value",`Node ${t}: invalid value element "${g}"`);let V=l.refs;if(Array.isArray(V)){let g=new Set;V.forEach((A,O)=>{let J=A??{},U=`${n}.metadata.refs[${O}]`,k=J.id;typeof k!="string"||!k.trim()?e(`${U}.id`,"ref-id-required",`Node ${t}: ref is missing an id`):g.has(k)?e(`${U}.id`,"duplicate-ref-id",`Node ${t}: duplicate ref id "${k}"`):g.add(k),(typeof J.url!="string"||!J.url.trim())&&e(`${U}.url`,"ref-url-required",`Node ${t}: ref "${k}" is missing a url`),J.status_mapped!==void 0&&!C.includes(J.status_mapped)&&e(`${U}.status_mapped`,"valid-status",`Node ${t}: ref "${k}" has invalid status_mapped "${J.status_mapped}"`)})}if(c==="flow"){let g=l.playlist;!s.metadata||!g||!g.entries?e(`${n}.metadata.playlist`,"flow-playlist-required",`Flow ${t}: missing metadata.playlist.entries`):g.entries.length===0&&r(`${n}.metadata.playlist`,"flow-playlist-empty",`Flow ${t}: playlist is empty`)}});let o=p.root_node_id;o&&!I.has(o)&&e("project.root_node_id","root-node-exists",`project.root_node_id "${o}" does not reference an existing node`);let d=b?.maps;if(Array.isArray(d)){let s=new Set;d.forEach((u,n)=>{if(typeof u!="object"||u===null||Array.isArray(u))return;let t=u,c=`project.metadata.maps[${n}]`,i=typeof t.id=="string"?t.id:void 0;i!==void 0&&(s.has(i)&&r(`${c}.id`,"map-duplicate-id",`Duplicate map id "${i}"`),s.add(i),ne(i)&&r(`${c}.id`,"map-shadows-built-in",`Map id "${i}" shadows a built-in map and will be ignored`));let m=t.root_node_id;typeof m=="string"&&!I.has(m)&&r(`${c}.root_node_id`,"map-unknown-root",`Map "${i??n}" anchors on "${m}" which does not reference an existing node`),Array.isArray(t.species)&&t.species.forEach((l,x)=>{typeof l=="string"&&!G.includes(l)&&r(`${c}.species[${x}]`,"map-unknown-species",`Map "${i??n}" filters on unknown species "${l}"`)}),Array.isArray(t.edge_types)&&t.edge_types.forEach((l,x)=>{typeof l=="string"&&!K.includes(l)&&r(`${c}.edge_types[${x}]`,"map-unknown-edge-type",`Map "${i??n}" filters on unknown edge type "${l}"`)})})}let w=new Set,S=new Set,j=new Set;h.forEach((s,u)=>{let n=`edges[${u}]`,t=s.id,c=s.source_id,i=s.target_id,m=s.edge_type;w.has(t)&&e(`${n}.id`,"duplicate-edge-id",`Duplicate edge ID: ${t}`),w.add(t);let l=`e-${c}-${i}`;t!==l&&r(`${n}.id`,"edge-id-convention",`Edge ${t}: id does not match convention "${l}" (stale after a rename?)`);let x=`${c}->${i}:${m}`;S.has(x)&&r(`${n}`,"duplicate-edge-relationship",`Duplicate edge relationship: ${x}`),S.add(x),s.project_id!==p.id&&e(`${n}.project_id`,"project-id-match",`Edge ${t}: project_id does not match project.id`),I.has(c)||e(`${n}.source_id`,"dangling-edge",`Edge ${t}: source_id "${c}" not found in nodes`),I.has(i)||e(`${n}.target_id`,"dangling-edge",`Edge ${t}: target_id "${i}" not found in nodes`),K.includes(m)||e(`${n}.edge_type`,"valid-edge-type",`Edge ${t}: invalid edge_type "${m}"`);let N=R.get(c),D=R.get(i),T=ue[m];N&&D&&T&&(T.some(([V,g])=>V===N.species&&g===D.species)||e(`${n}.edge_type`,"edge-semantics",`Edge ${t}: "${m}" not valid from ${N.species} to ${D.species}`)),m==="composes"&&j.add(`${c}->${i}`)});let F=(s,u,n,t=0)=>{if(t>50)return e(n,"playlist-depth",`Flow ${u}: playlist nesting too deep (possible cycle)`),[];let c=[];for(let i of s)if(i.type==="view")I.has(i.view_id)||e(n,"playlist-ref-exists",`Flow ${u}: playlist references non-existent view "${i.view_id}"`),c.push(i.view_id);else if(i.type==="flow")I.has(i.flow_id)||e(n,"playlist-ref-exists",`Flow ${u}: playlist references non-existent flow "${i.flow_id}"`),i.flow_id===u&&e(n,"playlist-self-cycle",`Flow ${u}: playlist contains itself (direct cycle)`),c.push(i.flow_id);else if(i.type==="condition")i.if_true&&c.push(...F(i.if_true,u,n,t+1)),i.if_false&&c.push(...F(i.if_false,u,n,t+1));else if(i.type==="junction"&&i.cases)for(let m of i.cases)c.push(...F(m.entries||[],u,n,t+1));return c};E.forEach((s,u)=>{let n=s.metadata;if(s.species==="flow"&&n?.playlist?.entries){let t=`nodes[${u}].metadata.playlist`,c=s.id,i=F(n.playlist.entries,c,t);for(let m of i)j.has(`${c}->${m}`)||e(t,"playlist-composes-coherence",`Flow ${c}: playlist references "${m}" but no composes edge exists`)}});let W=new Map,H=new Map;E.forEach((s,u)=>{let n=s.metadata;if(s.species==="flow"&&n?.playlist?.entries){let t=s.id,c=[],i=m=>{for(let l of m)if(l.type==="flow"&&c.push(l.flow_id),l.type==="condition"&&(l.if_true&&i(l.if_true),l.if_false&&i(l.if_false)),l.type==="junction"&&l.cases)for(let x of l.cases)i(x.entries||[])};i(n.playlist.entries),W.set(t,c),H.set(t,`nodes[${u}].metadata.playlist`)}});let Y=new Set,z=new Set,X=s=>{if(z.has(s))return!0;if(Y.has(s))return!1;Y.add(s),z.add(s);for(let u of W.get(s)||[])if(X(u))return e(H.get(s)??"","flow-cycle",`Cycle detected: flow "${s}" -> "${u}"`),!0;return z.delete(s),!1};for(let s of W.keys())X(s);for(let s of te(v))a.push(s);return $()}var ae="journal.jsonl";function L(f,a){return f.filter(e=>e?.species===a).length}function ge(){let f=process.argv[2];f||(console.error("Usage: node validate-bundle.js <path-to-bundle.json>"),process.exit(1)),(0,P.existsSync)(f)||(console.error(`File not found: ${f}`),process.exit(1));let a;try{a=JSON.parse((0,P.readFileSync)(f,"utf8"))}catch(h){console.error(`FATAL: Cannot parse JSON \u2014 ${h.message}`),process.exit(1)}let e=a;(typeof e!="object"||e===null||!e.project||!e.nodes||!e.edges)&&(console.error("FATAL: Missing top-level keys (project, nodes, edges)."),process.exit(1));let r=[],$=!1;if(e.journal===void 0){let h=(0,B.join)((0,B.dirname)(f),ae);if((0,P.existsSync)(h)){let{events:R,findings:I}=ee((0,P.readFileSync)(h,"utf8"));r=I,$=!0,e.journal=R}}let v=Array.isArray(e.nodes)?e.nodes:[],p=Array.isArray(e.edges)?e.edges:[],y=Array.isArray(e.journal)?e.journal:[],_=re(a);console.log(`
+  Arkaik Bundle Validation`),console.log(`  =======================
+`),console.log(`  Nodes: ${v.length} (${L(v,"view")} views, ${L(v,"flow")} flows, ${L(v,"data-model")} data-models, ${L(v,"api-endpoint")} api-endpoints, ${L(v,"acceptance")} acceptances)`),console.log(`  Edges: ${p.length}`),$?console.log(`  Journal: ${y.length} event(s) from ${ae} sidecar`):y.length>0&&console.log(`  Journal: ${y.length} embedded event(s)`),console.log(""),_.warnings.length>0&&(console.log(`  Warnings: ${_.warnings.length}`),_.warnings.forEach(h=>console.log(`    WARN: ${h.message}`)),console.log(""));let E=[...r.map(h=>h.message),..._.errors.map(h=>h.message)];E.length===0&&(console.log(`  Result: VALID
+`),process.exit(0)),console.log(`  Errors: ${E.length}`),E.forEach(h=>console.log(`    ERROR: ${h}`)),console.log(`
+  Result: INVALID
+`),process.exit(1)}ge();