@poa-box/agent 0.1.0

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

@@ -0,0 +1,36 @@
+/**
+ * Brain doc schemas — write-time shape validation (Task #346, HB#168).
+ *
+ * Retro #1 change #5: currently applyBrainChange() accepts any doc shape
+ * and the projection layer (brain-projections.ts) tolerates bad shapes at
+ * read time via formatTimestamp() and schema-tolerant renderers. That
+ * approach means bad data enters the doc and stays forever (Automerge
+ * field renames are merge hazards per HB#248). This module validates
+ * shape at WRITE time so canonically-broken entries never enter the doc.
+ *
+ * DESIGN:
+ * - Per-doc-id validators. pop.brain.shared, pop.brain.projects,
+ *   pop.brain.retros each have their own shape. Unknown doc ids return
+ *   `{ ok: true, warnings: [...] }` — permissionless schema evolution.
+ * - Validators check ITEMS of known arrays for required fields. Extra
+ *   fields are allowed (extensibility); missing required fields are errors.
+ * - applyBrainChange diffs pre-vs-post validity: if the pre-change doc
+ *   was already invalid, the bad state was inherited, not introduced, and
+ *   the new write is NOT rejected. Only regressions (valid → invalid) are
+ *   rejected. This preserves the constraint "existing bad entries stay
+ *   readable" while still preventing new bad writes.
+ * - Per-command --allow-invalid-shape bypass lives at the CLI layer and is
+ *   plumbed through applyBrainChange's options bag.
+ *
+ * SCHEMAS ARE DEFINED ONCE HERE and NOT duplicated in the CLI commands.
+ */
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Dispatch entry point. Returns { ok, errors, warnings }. Unknown doc ids
+ * are permitted (schema evolution) with a warning, not an error.
+ */
+export declare function validateBrainDocShape(docId: string, doc: any): ValidationResult;

package/dist/lib/brain-schemas.js

@@ -0,0 +1,316 @@
+"use strict";
+/**
+ * Brain doc schemas — write-time shape validation (Task #346, HB#168).
+ *
+ * Retro #1 change #5: currently applyBrainChange() accepts any doc shape
+ * and the projection layer (brain-projections.ts) tolerates bad shapes at
+ * read time via formatTimestamp() and schema-tolerant renderers. That
+ * approach means bad data enters the doc and stays forever (Automerge
+ * field renames are merge hazards per HB#248). This module validates
+ * shape at WRITE time so canonically-broken entries never enter the doc.
+ *
+ * DESIGN:
+ * - Per-doc-id validators. pop.brain.shared, pop.brain.projects,
+ *   pop.brain.retros each have their own shape. Unknown doc ids return
+ *   `{ ok: true, warnings: [...] }` — permissionless schema evolution.
+ * - Validators check ITEMS of known arrays for required fields. Extra
+ *   fields are allowed (extensibility); missing required fields are errors.
+ * - applyBrainChange diffs pre-vs-post validity: if the pre-change doc
+ *   was already invalid, the bad state was inherited, not introduced, and
+ *   the new write is NOT rejected. Only regressions (valid → invalid) are
+ *   rejected. This preserves the constraint "existing bad entries stay
+ *   readable" while still preventing new bad writes.
+ * - Per-command --allow-invalid-shape bypass lives at the CLI layer and is
+ *   plumbed through applyBrainChange's options bag.
+ *
+ * SCHEMAS ARE DEFINED ONCE HERE and NOT duplicated in the CLI commands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBrainDocShape = validateBrainDocShape;
+/**
+ * Lesson schema used by pop.brain.shared and (historically) pop.brain.lessons.
+ * Canonical shape: { id, author, title, body, timestamp, removed? }.
+ * Legacy tolerance: `text` is accepted as a synonym for `body`, `ts` for
+ * `timestamp` — the projection layer reads both (HB#297 formatTimestamp).
+ * A lesson must have at least one of {body, text} AND at least one of
+ * {title, id}. That's the minimum renderable shape.
+ */
+function validateLesson(lesson, index, errors) {
+    if (lesson == null || typeof lesson !== 'object') {
+        errors.push(`lessons[${index}]: not an object`);
+        return;
+    }
+    const hasBody = (typeof lesson.body === 'string' && lesson.body.length > 0) ||
+        (typeof lesson.text === 'string' && lesson.text.length > 0);
+    if (!hasBody) {
+        errors.push(`lessons[${index}]: missing required body/text (one must be a non-empty string)`);
+    }
+    const hasTitle = (typeof lesson.title === 'string' && lesson.title.length > 0) ||
+        (typeof lesson.id === 'string' && lesson.id.length > 0);
+    if (!hasTitle) {
+        errors.push(`lessons[${index}]: missing required title/id (one must be a non-empty string)`);
+    }
+    if (lesson.timestamp != null && lesson.ts != null) {
+        // Not an error; just unusual. Don't warn noisily.
+    }
+    if (lesson.timestamp != null &&
+        typeof lesson.timestamp !== 'number' &&
+        typeof lesson.timestamp !== 'string') {
+        errors.push(`lessons[${index}]: timestamp must be number or ISO string`);
+    }
+    // Task #347: optional tags field. Must be an array of strings when present.
+    // Backwards compatible: existing lessons without tags still validate.
+    // Tag vocabulary is free-form — no enforcement of category:/topic:/etc.
+    if (lesson.tags != null) {
+        if (!Array.isArray(lesson.tags)) {
+            errors.push(`lessons[${index}]: tags must be an array of strings`);
+        }
+        else {
+            for (let i = 0; i < lesson.tags.length; i++) {
+                if (typeof lesson.tags[i] !== 'string') {
+                    errors.push(`lessons[${index}]: tags[${i}] must be a string`);
+                }
+            }
+        }
+    }
+}
+function validateRule(rule, index, errors) {
+    if (rule == null || typeof rule !== 'object') {
+        errors.push(`rules[${index}]: not an object`);
+        return;
+    }
+    if (typeof rule.text !== 'string' || rule.text.length === 0) {
+        errors.push(`rules[${index}]: missing required text (non-empty string)`);
+    }
+}
+/**
+ * pop.brain.shared — lessons + rules + operatingConstraints + orgState.
+ * Arrays are optional (first-write bootstrap) but when present their items
+ * must validate.
+ */
+function validateSharedDoc(doc, errors, warnings) {
+    if (doc == null || typeof doc !== 'object') {
+        errors.push('pop.brain.shared: doc is not an object');
+        return;
+    }
+    if (doc.lessons != null) {
+        if (!Array.isArray(doc.lessons)) {
+            errors.push('pop.brain.shared: lessons must be an array');
+        }
+        else {
+            doc.lessons.forEach((l, i) => validateLesson(l, i, errors));
+        }
+    }
+    if (doc.rules != null) {
+        if (!Array.isArray(doc.rules)) {
+            errors.push('pop.brain.shared: rules must be an array');
+        }
+        else {
+            doc.rules.forEach((r, i) => validateRule(r, i, errors));
+        }
+    }
+    if (doc.operatingConstraints != null && !Array.isArray(doc.operatingConstraints)) {
+        errors.push('pop.brain.shared: operatingConstraints must be an array');
+    }
+    if (doc.orgState != null && typeof doc.orgState !== 'object') {
+        errors.push('pop.brain.shared: orgState must be an object');
+    }
+    void warnings;
+}
+// HB#183 (lesson cross-module-enum-drift): the source of truth for the
+// project lifecycle stages is the ProjectStage union type in
+// src/lib/brain-projections.ts. We MUST NOT retype the values here —
+// drift between the schema and the projection breaks at runtime
+// (HB#180 incident: schema enum was {proposed, building, ...},
+// canonical was {propose, discuss, ...}, validator rejected legitimate
+// new-project writes). The literal-array-as-type pattern below lets
+// TypeScript keep both the runtime Set and the union type in sync from
+// one declaration. If the canonical lifecycle ever changes,
+// brain-projections.ts ProjectStage stays the source of truth — update
+// that union, then update PROJECT_STAGES here in lockstep, and the
+// vitest "accepts all canonical lifecycle stages" case fails loudly
+// if drift creeps back in.
+// The literal tuple is what gives us a runtime Set; the satisfies clause
+// below proves at compile time that this list is structurally identical
+// to the ProjectStage union from brain-projections. If brain-projections
+// adds or removes a stage and this list isn't updated, tsc fails the
+// build at the satisfies line — drift is impossible.
+const PROJECT_STAGES = ['propose', 'discuss', 'plan', 'vote', 'execute', 'review', 'ship'];
+// Compile-time bidirectional drift check.
+// Direction 1 (literal → union): every literal in PROJECT_STAGES must
+// be a valid ProjectStage. tsc fails if you add a typo to the tuple.
+const _stagesAreValid = PROJECT_STAGES;
+const _stagesMatchUnion = true;
+void _stagesAreValid;
+void _stagesMatchUnion;
+const VALID_PROJECT_STAGES = new Set(PROJECT_STAGES);
+function validateProject(p, index, errors) {
+    if (p == null || typeof p !== 'object') {
+        errors.push(`projects[${index}]: not an object`);
+        return;
+    }
+    if (typeof p.id !== 'string' || p.id.length === 0) {
+        errors.push(`projects[${index}]: missing required id (non-empty string)`);
+    }
+    if (typeof p.name !== 'string' || p.name.length === 0) {
+        errors.push(`projects[${index}]: missing required name (non-empty string)`);
+    }
+    if (typeof p.stage !== 'string' || !VALID_PROJECT_STAGES.has(p.stage)) {
+        errors.push(`projects[${index}]: stage must be one of ${[...VALID_PROJECT_STAGES].join('|')}, got ${JSON.stringify(p.stage)}`);
+    }
+}
+function validateProjectsDoc(doc, errors) {
+    if (doc == null || typeof doc !== 'object') {
+        errors.push('pop.brain.projects: doc is not an object');
+        return;
+    }
+    if (doc.projects != null) {
+        if (!Array.isArray(doc.projects)) {
+            errors.push('pop.brain.projects: projects must be an array');
+        }
+        else {
+            doc.projects.forEach((p, i) => validateProject(p, i, errors));
+        }
+    }
+}
+function validateRetro(r, index, errors) {
+    if (r == null || typeof r !== 'object') {
+        errors.push(`retros[${index}]: not an object`);
+        return;
+    }
+    if (typeof r.id !== 'string' || r.id.length === 0) {
+        errors.push(`retros[${index}]: missing required id`);
+    }
+    if (r.proposedChanges != null && !Array.isArray(r.proposedChanges)) {
+        errors.push(`retros[${index}]: proposedChanges must be an array`);
+    }
+    if (r.discussion != null && !Array.isArray(r.discussion)) {
+        errors.push(`retros[${index}]: discussion must be an array`);
+    }
+}
+function validateRetrosDoc(doc, errors) {
+    if (doc == null || typeof doc !== 'object') {
+        errors.push('pop.brain.retros: doc is not an object');
+        return;
+    }
+    if (doc.retros != null) {
+        if (!Array.isArray(doc.retros)) {
+            errors.push('pop.brain.retros: retros must be an array');
+        }
+        else {
+            doc.retros.forEach((r, i) => validateRetro(r, i, errors));
+        }
+    }
+}
+// --- pop.brain.brainstorms (task #354 phase a, HB#207) -------------
+//
+// Brainstorms are a forward-looking cross-agent ideation surface:
+// { id, title, prompt, author, status, ideas[], window, removed? }.
+// Distinct from pop.brain.retros (reactive session retrospectives)
+// and pop.brain.projects (lifecycle state machine) — this doc is
+// where new questions get posted, ideas get debated + voted, and
+// top-ranked ideas get promoted to pop.brain.projects at the propose
+// stage. See docs/agents/brain-layer-setup.md and the #354 task description
+// for the full lifecycle.
+const VALID_BRAINSTORM_STATUSES = ['open', 'voting', 'closed', 'promoted'];
+const VALID_BRAINSTORM_STATUS_SET = new Set(VALID_BRAINSTORM_STATUSES);
+const VALID_VOTE_STANCES = ['support', 'explore', 'oppose'];
+const VALID_VOTE_STANCE_SET = new Set(VALID_VOTE_STANCES);
+function validateIdea(idea, brainstormId, ideaIndex, errors) {
+    if (idea == null || typeof idea !== 'object') {
+        errors.push(`brainstorms[${brainstormId}].ideas[${ideaIndex}]: not an object`);
+        return;
+    }
+    if (typeof idea.id !== 'string' || idea.id.length === 0) {
+        errors.push(`brainstorms[${brainstormId}].ideas[${ideaIndex}]: missing required id`);
+    }
+    if (typeof idea.message !== 'string' || idea.message.length === 0) {
+        errors.push(`brainstorms[${brainstormId}].ideas[${ideaIndex}]: missing required message`);
+    }
+    if (idea.author != null && typeof idea.author !== 'string') {
+        errors.push(`brainstorms[${brainstormId}].ideas[${ideaIndex}]: author must be a string when present`);
+    }
+    if (idea.votes != null) {
+        if (typeof idea.votes !== 'object' || Array.isArray(idea.votes)) {
+            errors.push(`brainstorms[${brainstormId}].ideas[${ideaIndex}]: votes must be an object keyed by agent address`);
+        }
+        else {
+            for (const [addr, stance] of Object.entries(idea.votes)) {
+                if (typeof stance !== 'string' || !VALID_VOTE_STANCE_SET.has(stance)) {
+                    errors.push(`brainstorms[${brainstormId}].ideas[${ideaIndex}].votes[${addr}]: stance must be one of ${[...VALID_VOTE_STANCES].join('|')}, got ${JSON.stringify(stance)}`);
+                }
+            }
+        }
+    }
+    if (idea.priority != null && !['high', 'medium', 'low'].includes(idea.priority)) {
+        errors.push(`brainstorms[${brainstormId}].ideas[${ideaIndex}]: priority must be high|medium|low when present`);
+    }
+}
+function validateBrainstorm(b, index, errors) {
+    if (b == null || typeof b !== 'object') {
+        errors.push(`brainstorms[${index}]: not an object`);
+        return;
+    }
+    const bid = b.id ?? `<index ${index}>`;
+    if (typeof b.id !== 'string' || b.id.length === 0) {
+        errors.push(`brainstorms[${index}]: missing required id`);
+    }
+    if (typeof b.title !== 'string' || b.title.length === 0) {
+        errors.push(`brainstorms[${bid}]: missing required title`);
+    }
+    if (typeof b.status !== 'string' || !VALID_BRAINSTORM_STATUS_SET.has(b.status)) {
+        errors.push(`brainstorms[${bid}]: status must be one of ${[...VALID_BRAINSTORM_STATUSES].join('|')}, got ${JSON.stringify(b.status)}`);
+    }
+    if (b.ideas != null) {
+        if (!Array.isArray(b.ideas)) {
+            errors.push(`brainstorms[${bid}]: ideas must be an array`);
+        }
+        else {
+            b.ideas.forEach((idea, i) => validateIdea(idea, bid, i, errors));
+        }
+    }
+    if (b.promotedToProjectIds != null && !Array.isArray(b.promotedToProjectIds)) {
+        errors.push(`brainstorms[${bid}]: promotedToProjectIds must be an array`);
+    }
+}
+function validateBrainstormsDoc(doc, errors) {
+    if (doc == null || typeof doc !== 'object') {
+        errors.push('pop.brain.brainstorms: doc is not an object');
+        return;
+    }
+    if (doc.brainstorms != null) {
+        if (!Array.isArray(doc.brainstorms)) {
+            errors.push('pop.brain.brainstorms: brainstorms must be an array');
+        }
+        else {
+            doc.brainstorms.forEach((b, i) => validateBrainstorm(b, i, errors));
+        }
+    }
+}
+/**
+ * Dispatch entry point. Returns { ok, errors, warnings }. Unknown doc ids
+ * are permitted (schema evolution) with a warning, not an error.
+ */
+function validateBrainDocShape(docId, doc) {
+    const errors = [];
+    const warnings = [];
+    switch (docId) {
+        case 'pop.brain.shared':
+        case 'pop.brain.lessons':
+            validateSharedDoc(doc, errors, warnings);
+            break;
+        case 'pop.brain.projects':
+            validateProjectsDoc(doc, errors);
+            break;
+        case 'pop.brain.retros':
+            validateRetrosDoc(doc, errors);
+            break;
+        case 'pop.brain.brainstorms':
+            validateBrainstormsDoc(doc, errors);
+            break;
+        default:
+            warnings.push(`unknown doc id "${docId}" — no schema registered, accepting any shape. ` +
+                `Add a validator to src/lib/brain-schemas.ts to enforce one.`);
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Brain-layer change signing — ECDSA over snapshot bytes.
+ *
+ * Each brain CRDT change gets wrapped in a signed envelope before being
+ * written to the blockstore. The envelope's sig authenticates the full
+ * Automerge snapshot against an Ethereum address derived from the
+ * existing POP_PRIVATE_KEY. No Nostr keys, no Schnorr, no second PKI.
+ *
+ * Envelope format (v1):
+ *
+ *     {
+ *       v: 1,
+ *       author: "0xABCD...",        // Ethereum address (lowercase)
+ *       timestamp: 1776200000,      // unix seconds
+ *       automerge: "0xDEADBEEF",    // full Automerge.save() bytes, hex
+ *       sig: "0xABC..."             // ECDSA over keccak256(author|ts|automerge)
+ *     }
+ *
+ * Serialized as UTF-8 JSON, stored as a raw-codec IPLD block. The CID
+ * covers the whole envelope, so the sig is content-addressed alongside
+ * the data it authenticates.
+ *
+ * On read, the projection layer:
+ *   1. Unmarshal the envelope JSON
+ *   2. Verify the sig recovers to `author`
+ *   3. Check `author` against the allowlist at
+ *      agent/brain/Config/brain-allowlist.json
+ *   4. If all OK, extract the Automerge bytes and merge
+ *
+ * Sync layer stays permissionless — any peer can gossip any CID. Auth
+ * happens at read time so the network is resilient against relay
+ * operators (there are none, but the principle stands for any future
+ * transport).
+ */
+export interface BrainChangeEnvelope {
+    v: 1;
+    author: string;
+    timestamp: number;
+    automerge: string;
+    sig: string;
+}
+/**
+ * Sign an Automerge snapshot with the wallet derived from POP_PRIVATE_KEY.
+ * Returns a v1 envelope ready to be JSON-encoded and written as a block.
+ */
+export declare function signBrainChange(automergeBytes: Uint8Array, privateKey?: string): Promise<BrainChangeEnvelope>;
+/**
+ * Verify an envelope's signature and return the recovered author.
+ * Throws if the envelope is malformed or the signature doesn't verify.
+ *
+ * NOTE: this only checks authenticity (sig corresponds to `author`);
+ * it does NOT check authorization (whether `author` is allowed to
+ * write to this doc). That's the allowlist check — see isAllowedAuthor.
+ */
+export declare function verifyBrainChange(envelope: BrainChangeEnvelope): string;
+/**
+ * Extract the Automerge snapshot bytes from an envelope.
+ * Does NOT verify the signature — caller must run verifyBrainChange first.
+ */
+export declare function unwrapAutomergeBytes(envelope: BrainChangeEnvelope): Uint8Array;
+export interface AllowlistEntry {
+    address: string;
+    name?: string;
+    addedAt?: string;
+    addedBy?: string;
+}
+/**
+ * Path to the git-tracked brain-allowlist.json. Single source of truth
+ * for who is permitted to write to brain docs. Edited via governance
+ * (or via `pop brain allowlist add/remove`, which writes to the same
+ * file and leaves the git review gate in place).
+ *
+ * Exported so command handlers can write to the same path without
+ * hard-coding it independently.
+ */
+export declare function getAllowlistPath(): string;
+export declare function loadAllowlist(): AllowlistEntry[];
+/**
+ * Check whether a given address is in the allowlist.
+ * Case-insensitive on the address.
+ */
+export declare function isAllowedAuthor(address: string): boolean;
+/**
+ * Combined auth check: verify signature + allowlist membership.
+ * Returns the authenticated author on success; throws otherwise.
+ */
+export declare function authenticateAndAuthorize(envelope: BrainChangeEnvelope): string;
+export type AuthorizationMode = 'dynamic' | 'static-fallback' | 'both-agree';
+export interface AuthorizationResult {
+    allowed: boolean;
+    mode: AuthorizationMode;
+    /** Populated only when fallback fired. Empty string otherwise. */
+    fallbackReason: string;
+}
+/**
+ * Async authorization check: on-chain org membership first, static
+ * JSON allowlist second. Does NOT throw — returns a result object the
+ * caller can inspect for logging purposes. Callers then decide whether
+ * to reject the change or accept it based on `.allowed`.
+ *
+ * This is the new canonical authorization for brain read paths.
+ */
+export declare function isAuthorizedAuthor(address: string): Promise<AuthorizationResult>;