@poa-box/agent 0.1.0

package/dist/lib/brain-projections.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Brain projections — pure functions that render an Automerge brain doc
+ * (as a plain JS object) to human-readable markdown.
+ *
+ * Called by `pop brain snapshot --doc <id>` and by the heartbeat skill
+ * at end of heartbeat. The output is a .generated.md file that lives
+ * alongside the hand-written brain knowledge files; step 8 of the plan
+ * is when the hand-written files are retired and the projection becomes
+ * the source of truth.
+ *
+ * ## Design notes
+ *
+ * - **Pure functions only.** No I/O, no CLI state, no Date.now(). Makes
+ *   them trivially testable and idempotent: same input → byte-identical
+ *   output.
+ *
+ * - **Schema-tolerant.** The current pop.brain.shared schema stores a
+ *   `lessons` list. Older revisions may use `rules` / `operatingConstraints` /
+ *   `orgState`. The projection renders whichever of those fields exist,
+ *   in a canonical order, and falls back to a JSON dump for any
+ *   unrecognized fields so future schema changes don't silently drop data.
+ *
+ * - **Top-of-file banner.** Every generated file starts with a
+ *   DO-NOT-HAND-EDIT banner so reviewers can spot a hand-edit in a diff.
+ *
+ * - **Stable field ordering.** Lessons (and other lists) are rendered in
+ *   index order. If we later want time-sorted output, sort by timestamp
+ *   inside the renderer — do NOT sort by ID (the CRDT list order is
+ *   already deterministic across replicas thanks to Automerge).
+ */
+/**
+ * Shape of the pop.brain.shared doc. Fields are optional because the
+ * doc evolves over time and early snapshots may lack newer sections.
+ */
+export interface SharedBrainDoc {
+    lessons?: Array<{
+        id?: string;
+        author?: string;
+        title?: string;
+        text?: string;
+        body?: string;
+        timestamp?: number;
+        [k: string]: any;
+    }>;
+    rules?: Array<{
+        id?: string;
+        author?: string;
+        text?: string;
+        timestamp?: number;
+        [k: string]: any;
+    }>;
+    operatingConstraints?: Array<any>;
+    orgState?: Record<string, any>;
+    [k: string]: any;
+}
+/**
+ * Project a pop.brain.shared doc to markdown.
+ *
+ * Pure function — given the same input JS object, returns the exact
+ * same string every time. No Date.now(), no environment reads, no I/O.
+ *
+ * @param doc      The Automerge doc as a plain JS object (from Automerge.toJS)
+ * @param headCid  Optional head CID to include in the header for traceability
+ */
+export declare function projectShared(doc: SharedBrainDoc, headCid?: string | null): string;
+export type ProjectStage = 'propose' | 'discuss' | 'plan' | 'vote' | 'execute' | 'review' | 'ship';
+export interface ProjectDiscussionEntry {
+    author?: string;
+    ipfs?: string;
+    message?: string;
+    stance?: 'support' | 'oppose' | 'concerned' | 'question' | 'neutral';
+    timestamp?: number;
+    [k: string]: any;
+}
+export interface BrainProject {
+    id: string;
+    name: string;
+    stage: ProjectStage;
+    proposedBy?: string;
+    /** Heartbeat number at proposal time (prose-era projects from projects.md). */
+    proposedAtHB?: number;
+    /** Unix-seconds timestamp at proposal time (CLI-created projects from `pop brain new-project`). */
+    proposedAt?: number;
+    /** Unix-seconds timestamp of the most recent `pop brain advance-stage` transition. */
+    lastStageAdvanceAt?: number;
+    /** Soft-delete tombstone — set by `pop brain remove-project`. Filtered from projections. */
+    removed?: boolean;
+    removedAt?: number;
+    removedBy?: string;
+    removedReason?: string;
+    brief?: string;
+    discussion?: ProjectDiscussionEntry[];
+    taskPlan?: string;
+    proposal?: string;
+    retrospective?: string;
+    [k: string]: any;
+}
+export interface ProjectsBrainDoc {
+    projects?: BrainProject[];
+    [k: string]: any;
+}
+/**
+ * Project a pop.brain.projects doc to markdown.
+ *
+ * Pure function — same input produces byte-identical output.
+ * Schema-tolerant: missing project fields are skipped, unknown
+ * top-level fields dump as JSON, empty doc renders a placeholder
+ * rather than crashing or returning an empty string.
+ */
+export declare function projectProjects(doc: ProjectsBrainDoc, headCid?: string | null): string;
+export type RetroChangeStatus = 'proposed' | 'agreed' | 'modified' | 'rejected' | 'filed';
+export type RetroStatus = 'open' | 'discussed' | 'shipped';
+export type RetroVote = 'agree' | 'modify' | 'reject';
+export interface RetroProposedChange {
+    id: string;
+    summary: string;
+    details?: string;
+    status: RetroChangeStatus;
+    filedTaskId?: string;
+    [k: string]: any;
+}
+export interface RetroDiscussionEntry {
+    author?: string;
+    hb?: number;
+    message?: string;
+    votePerChange?: Record<string, RetroVote>;
+    timestamp?: number;
+    [k: string]: any;
+}
+export interface BrainRetro {
+    id: string;
+    author?: string;
+    hb?: number;
+    window?: {
+        from?: number;
+        to?: number;
+    };
+    observations?: {
+        worked?: string;
+        didntWork?: string;
+    };
+    proposedChanges?: RetroProposedChange[];
+    discussion?: RetroDiscussionEntry[];
+    status?: RetroStatus;
+    createdAt?: number;
+    closedAt?: number;
+    removed?: boolean;
+    removedAt?: number;
+    removedBy?: string;
+    removedReason?: string;
+    [k: string]: any;
+}
+export interface RetrosBrainDoc {
+    retros?: BrainRetro[];
+    [k: string]: any;
+}
+/**
+ * Project a pop.brain.retros doc to markdown.
+ *
+ * Same invariants as projectShared / projectProjects: pure function,
+ * schema-tolerant, empty doc renders a placeholder.
+ */
+export declare function projectRetros(doc: RetrosBrainDoc, headCid?: string | null): string;
+export interface BrainstormIdea {
+    id: string;
+    author?: string;
+    message: string;
+    timestamp?: number;
+    votes?: Record<string, 'support' | 'explore' | 'oppose'>;
+    priority?: 'high' | 'medium' | 'low';
+    promotedAt?: number;
+    promotedBy?: string;
+    promotedProjectId?: string;
+    [k: string]: any;
+}
+export interface BrainstormDiscussionEntry {
+    author?: string;
+    message?: string;
+    timestamp?: number;
+    [k: string]: any;
+}
+export interface Brainstorm {
+    id: string;
+    title: string;
+    prompt?: string;
+    author?: string;
+    openedAt?: number;
+    status: 'open' | 'voting' | 'closed' | 'promoted';
+    window?: {
+        from?: number;
+        to?: number;
+    };
+    ideas?: BrainstormIdea[];
+    discussion?: BrainstormDiscussionEntry[];
+    promotedToProjectIds?: string[];
+    removed?: boolean;
+    removedAt?: number;
+    removedBy?: string;
+    removedReason?: string;
+    closedAt?: number;
+    closedBy?: string;
+    closedReason?: string;
+    [k: string]: any;
+}
+export interface BrainstormsBrainDoc {
+    brainstorms?: Brainstorm[];
+    [k: string]: any;
+}
+export declare function projectBrainstorms(doc: BrainstormsBrainDoc, headCid?: string | null): string;
+export type BrainProjectorFn = (doc: any, headCid: string | null) => string;
+/**
+ * Look up the right projector for a docId. Falls through to
+ * projectShared as the default so every previously-written snapshot
+ * call still works.
+ */
+export declare function projectForDoc(docId: string, doc: any, headCid: string | null): string;