@jungjaehoon/mama-os 0.41.0 → 0.43.0

package/dist/observability/operational-issues.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ISSUE_ERROR_CHARS = void 0;
+exports.ensureOperationalIssuesTable = ensureOperationalIssuesTable;
+exports.redactIssueError = redactIssueError;
+exports.issueDedupeKey = issueDedupeKey;
+exports.recordOperationalIssue = recordOperationalIssue;
+exports.listOpenOperationalIssues = listOpenOperationalIssues;
+exports.getOperationalIssue = getOperationalIssue;
+exports.setOperationalIssueStatus = setOperationalIssueStatus;
+exports.closeOperationalIssue = closeOperationalIssue;
+/**
+ * Operational issues: the system's own failures as first-class evidence.
+ *
+ * Every place a failure already passes through (gateway tool failure, envelope scope
+ * mismatch, dead owner-event batch, ledger stagnation) records one row here, aggregated
+ * by (surface, signature). Every packet carries the open rows, so the agent sees what is
+ * broken before it judges anything; the daily self-check turn triages them.
+ *
+ * Stored error text passes the secret scan first and FAILS CLOSED: a non-clean scan stores
+ * no original characters. This table is read into every prompt, which makes it a new place
+ * for credentials to land.
+ *
+ * Table: awareness_operational_issues in the mama-core database (migration 066 creates it
+ * on a fresh install; an installed table without `occurrences` gets the column here).
+ */
+const node_crypto_1 = require("node:crypto");
+const secret_filter_js_1 = require("../memory/secret-filter.js");
+const SURFACES = new Set([
+    'gateway',
+    'envelope',
+    'inbox',
+    'ledger',
+    'budget',
+    'delivery',
+]);
+const SEVERITIES = new Set(['info', 'warn', 'error']);
+const SEVERITY_RANK = { error: 0, warn: 1, info: 2 };
+exports.MAX_ISSUE_ERROR_CHARS = 2_000;
+const MAX_SIGNATURE_CHARS = 120;
+const TABLE_DDL = `
+  CREATE TABLE IF NOT EXISTS awareness_operational_issues (
+    issue_id TEXT PRIMARY KEY,
+    dedupe_key TEXT UNIQUE NOT NULL,
+    surface TEXT NOT NULL,
+    severity TEXT NOT NULL,
+    status TEXT NOT NULL,
+    source_delta_id TEXT,
+    first_seen_at INTEGER NOT NULL CHECK (first_seen_at >= 0),
+    last_seen_at INTEGER NOT NULL CHECK (last_seen_at >= first_seen_at),
+    next_retry_at INTEGER,
+    last_error TEXT,
+    owner_agent TEXT,
+    occurrences INTEGER NOT NULL DEFAULT 1
+  )`;
+/** Idempotent: creates the table on a bare DB, adds `occurrences` to an installed one. */
+function ensureOperationalIssuesTable(db) {
+    db.prepare(TABLE_DDL).run();
+    const columns = db.prepare('PRAGMA table_info(awareness_operational_issues)').all();
+    if (!columns.some((column) => column.name === 'occurrences')) {
+        db.prepare('ALTER TABLE awareness_operational_issues ADD COLUMN occurrences INTEGER NOT NULL DEFAULT 1').run();
+    }
+    db.prepare(`CREATE INDEX IF NOT EXISTS idx_awareness_operational_issues_status_seen
+       ON awareness_operational_issues(status, last_seen_at DESC)`).run();
+}
+/** Redaction gate, fail closed: a non-clean scan stores none of the original characters. */
+function redactIssueError(raw) {
+    const scan = (0, secret_filter_js_1.scanForSecrets)(raw);
+    if (!scan.clean) {
+        return `[redacted: ${scan.matches.join(',')}]`;
+    }
+    return raw.replace(/\s+/g, ' ').trim().slice(0, exports.MAX_ISSUE_ERROR_CHARS);
+}
+function digest(value) {
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, 24)}`;
+}
+function issueDedupeKey(surface, signature) {
+    return (0, node_crypto_1.createHash)('sha256').update(`${surface}\0${signature}`).digest('hex');
+}
+function recordOperationalIssue(db, input) {
+    if (!SURFACES.has(input.surface)) {
+        throw new Error(`operational issue: unknown surface ${String(input.surface)}`);
+    }
+    if (!SEVERITIES.has(input.severity)) {
+        throw new Error(`operational issue: unknown severity ${String(input.severity)}`);
+    }
+    const signature = input.signature.replace(/\s+/g, ' ').trim().slice(0, MAX_SIGNATURE_CHARS);
+    if (!signature) {
+        throw new Error('operational issue: signature is required');
+    }
+    const now = input.nowMs ?? Date.now();
+    const dedupeKey = issueDedupeKey(input.surface, signature);
+    const lastError = redactIssueError(input.error);
+    const sourceRef = input.sourceRef ? digest(input.sourceRef) : null;
+    const existing = db
+        .prepare(`SELECT issue_id, occurrences, status FROM awareness_operational_issues WHERE dedupe_key = ?`)
+        .all(dedupeKey);
+    if (existing.length > 0) {
+        const row = existing[0];
+        // A closed issue that recurs reopens: closure was a claim about the signature going quiet.
+        db.prepare(`UPDATE awareness_operational_issues
+          SET last_seen_at = MAX(last_seen_at, ?), occurrences = occurrences + 1,
+              last_error = ?, severity = ?, source_delta_id = COALESCE(?, source_delta_id),
+              owner_agent = COALESCE(?, owner_agent),
+              status = CASE WHEN status = 'closed' THEN 'open' ELSE status END
+        WHERE dedupe_key = ?`).run(now, `${signature} | ${lastError}`, input.severity, sourceRef, input.ownerAgent ?? null, dedupeKey);
+        return { issueId: row.issue_id, occurrences: row.occurrences + 1 };
+    }
+    const issueId = `iss_${dedupeKey.slice(0, 16)}`;
+    db.prepare(`INSERT INTO awareness_operational_issues
+       (issue_id, dedupe_key, surface, severity, status, source_delta_id, first_seen_at,
+        last_seen_at, next_retry_at, last_error, owner_agent, occurrences)
+     VALUES (?, ?, ?, ?, 'open', ?, ?, ?, NULL, ?, ?, 1)`).run(issueId, dedupeKey, input.surface, input.severity, sourceRef, now, now, `${signature} | ${lastError}`, input.ownerAgent ?? null);
+    return { issueId, occurrences: 1 };
+}
+function rowToIssue(row) {
+    const stored = typeof row.last_error === 'string' ? row.last_error : '';
+    const separator = stored.indexOf(' | ');
+    return {
+        issueId: String(row.issue_id),
+        surface: String(row.surface),
+        severity: String(row.severity),
+        status: String(row.status),
+        signature: separator > 0 ? stored.slice(0, separator) : stored,
+        lastError: separator > 0 ? stored.slice(separator + 3) : stored || null,
+        occurrences: Number(row.occurrences ?? 1),
+        firstSeenAt: Number(row.first_seen_at),
+        lastSeenAt: Number(row.last_seen_at),
+    };
+}
+/**
+ * Open issues: error before warn before info, then most recent, capped - ordered in SQL so an
+ * old error is never hidden behind newer info rows. `minSeverity` lets packets and the
+ * self-check turn skip designed refusals (info) while the table keeps counting them.
+ */
+function listOpenOperationalIssues(db, limit = 20, minSeverity = 'info') {
+    const maxRank = SEVERITY_RANK[minSeverity] ?? 2;
+    const rows = db
+        .prepare(`SELECT * FROM awareness_operational_issues
+        WHERE status <> 'closed'
+          AND (CASE severity WHEN 'error' THEN 0 WHEN 'warn' THEN 1 ELSE 2 END) <= ?
+        ORDER BY (CASE severity WHEN 'error' THEN 0 WHEN 'warn' THEN 1 ELSE 2 END) ASC,
+                 last_seen_at DESC
+        LIMIT ?`)
+        .all(maxRank, Math.min(Math.max(limit, 1), 200));
+    return rows.map(rowToIssue);
+}
+/** One issue by id, or null; the repair path checks existence before writing a bundle. */
+function getOperationalIssue(db, issueId) {
+    const rows = db
+        .prepare(`SELECT * FROM awareness_operational_issues WHERE issue_id = ?`)
+        .all(issueId);
+    return rows.length > 0 ? rowToIssue(rows[0]) : null;
+}
+function setOperationalIssueStatus(db, issueId, status) {
+    const result = db
+        .prepare(`UPDATE awareness_operational_issues SET status = ? WHERE issue_id = ?`)
+        .run(status, issueId);
+    if (!result || result.changes !== 1) {
+        throw new Error(`operational issue not found: ${issueId}`);
+    }
+}
+/** Closing is a claim that the signature went quiet; an unknown id is an error, not a no-op. */
+function closeOperationalIssue(db, issueId, reason) {
+    if (!reason.trim()) {
+        throw new Error('operational issue: a close reason is required');
+    }
+    setOperationalIssueStatus(db, issueId, 'closed');
+}
+//# sourceMappingURL=operational-issues.js.map

package/dist/observability/operational-issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operational-issues.js","sourceRoot":"","sources":["../../src/observability/operational-issues.ts"],"names":[],"mappings":"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"}

package/dist/operator/file-export.d.ts

@@ -0,0 +1,22 @@
+export type ExportFormat = 'csv' | 'md';
+export interface ExportFileInput {
+    format: ExportFormat;
+    name: string;
+    columns?: string[];
+    rows?: Array<Record<string, string | number | null>>;
+    content?: string;
+}
+export interface ExportFileResult {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export declare const EXPORT_DIR_NAME = "exports";
+/** The one place the exports root is computed. Mirrors owner-event-effects.ts (MAMA_WORKSPACE). */
+export declare function resolveExportRoot(env?: NodeJS.ProcessEnv): string;
+/** Safe basename: ascii letters, digits and dashes; everything else (including path parts) collapses. */
+export declare function slugExportName(name: string): string;
+export declare function renderCsv(rows: Array<Record<string, string | number | null>>, columns?: string[]): string;
+/** Pure apart from the write. Never overwrites; never escapes the root. */
+export declare function exportFile(input: ExportFileInput, root: string, nowMs?: number): Promise<ExportFileResult>;
+//# sourceMappingURL=file-export.d.ts.map

package/dist/operator/file-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-export.d.ts","sourceRoot":"","sources":["../../src/operator/file-export.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,IAAI,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,eAAe,YAAY,CAAC;AAIzC,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG9E;AAED,yGAAyG;AACzG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASnD;AAiBD,wBAAgB,SAAS,CACvB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC,EACnD,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CAQR;AASD,2EAA2E;AAC3E,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAmB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CA2C3B"}

package/dist/operator/file-export.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPORT_DIR_NAME = void 0;
+exports.resolveExportRoot = resolveExportRoot;
+exports.slugExportName = slugExportName;
+exports.renderCsv = renderCsv;
+exports.exportFile = exportFile;
+/**
+ * file_export: the smallest path from "make me a file" to a file the owner can receive.
+ *
+ * Writes only under the private workspace exports root (the same root telegram_send and
+ * drive_upload accept through resolvePrivateWorkspaceFile), never overwrites (wx flag),
+ * never escapes the root, and returns the bytes and sha256 the executor records as an
+ * effect. csv and md ship first: both need no dependency and both open where the owner
+ * works. Formula-leading cells are neutralised because the owner opens the csv in Excel.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+exports.EXPORT_DIR_NAME = 'exports';
+const MAX_ROWS = 5_000;
+const MAX_BYTES = 8 * 1024 * 1024;
+/** The one place the exports root is computed. Mirrors owner-event-effects.ts (MAMA_WORKSPACE). */
+function resolveExportRoot(env = process.env) {
+    const workspace = (0, node_path_1.resolve)(env.MAMA_WORKSPACE || (0, node_path_1.join)((0, node_os_1.homedir)(), '.mama', 'workspace'));
+    return (0, node_path_1.join)(workspace, exports.EXPORT_DIR_NAME);
+}
+/** Safe basename: ascii letters, digits and dashes; everything else (including path parts) collapses. */
+function slugExportName(name) {
+    const slug = name
+        .normalize('NFKD')
+        .replace(/[^\x20-\x7e]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+    return slug || 'export';
+}
+function csvCell(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    let text = String(value);
+    // A leading =, +, -, @ (or a tab/CR) is a formula to a spreadsheet: prefix an apostrophe.
+    if (/^[=+\-@\t\r]/.test(text)) {
+        text = `'${text}`;
+    }
+    if (/[",\r\n]/.test(text)) {
+        return `"${text.replace(/"/g, '""')}"`;
+    }
+    return text;
+}
+function renderCsv(rows, columns) {
+    const header = columns && columns.length > 0 ? columns : [...new Set(rows.flatMap((row) => Object.keys(row)))];
+    const lines = [header.map(csvCell).join(',')];
+    for (const row of rows) {
+        lines.push(header.map((column) => csvCell(row[column] ?? null)).join(','));
+    }
+    return `${lines.join('\r\n')}\r\n`;
+}
+function timestampSuffix(nowMs) {
+    return new Date(nowMs)
+        .toISOString()
+        .replace(/[-:]/g, '')
+        .replace(/\.\d{3}Z$/, 'Z');
+}
+/** Pure apart from the write. Never overwrites; never escapes the root. */
+async function exportFile(input, root, nowMs = Date.now()) {
+    if (input.format !== 'csv' && input.format !== 'md') {
+        throw new Error(`file_export: unsupported format ${String(input.format)}`);
+    }
+    let body;
+    if (input.format === 'csv') {
+        if (!Array.isArray(input.rows)) {
+            throw new Error('file_export: csv requires rows');
+        }
+        if (input.rows.length > MAX_ROWS) {
+            throw new Error(`file_export: csv rows exceed ${MAX_ROWS}`);
+        }
+        body = renderCsv(input.rows, input.columns);
+    }
+    else {
+        if (typeof input.content !== 'string' || input.content.trim() === '') {
+            throw new Error('file_export: md requires content');
+        }
+        body = input.content.endsWith('\n') ? input.content : `${input.content}\n`;
+    }
+    const bytes = Buffer.byteLength(body, 'utf-8');
+    if (bytes > MAX_BYTES) {
+        throw new Error(`file_export: ${bytes} bytes exceeds ${MAX_BYTES}`);
+    }
+    const realRoot = (0, node_path_1.resolve)(root);
+    (0, node_fs_1.mkdirSync)(realRoot, { recursive: true });
+    const base = `${slugExportName(input.name)}-${timestampSuffix(nowMs)}`;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        const fileName = `${base}${attempt === 0 ? '' : `-${attempt}`}.${input.format}`;
+        const path = (0, node_path_1.resolve)(realRoot, fileName);
+        if (path !== realRoot && !path.startsWith(`${realRoot}${node_path_1.sep}`)) {
+            throw new Error(`file_export: refusing to write outside ${realRoot}`);
+        }
+        try {
+            (0, node_fs_1.writeFileSync)(path, body, { encoding: 'utf-8', flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                continue; // never overwrite: same second, same name -> counter
+            }
+            throw error;
+        }
+        return { path, bytes, sha256: (0, node_crypto_1.createHash)('sha256').update(body).digest('hex') };
+    }
+    throw new Error('file_export: could not find a free file name');
+}
+//# sourceMappingURL=file-export.js.map

package/dist/operator/file-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-export.js","sourceRoot":"","sources":["../../src/operator/file-export.ts"],"names":[],"mappings":"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"}

package/dist/operator/learning-context.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Owner policy and lessons, injected into every turn.
+ *
+ * Conversation changes operations only if what the owner said reaches the next turn.
+ * Two kinds of memory rows do that: `policy:` rows (rules in force, rendered
+ * unconditionally for the turn's scope) and `lesson:` rows (corrections, ranked by the
+ * turn's query, bounded). Both are OWNER-authored data inside a trusted block, so every
+ * rendered value is markup-escaped and every line is budgeted before assembly: a stored
+ * string can never close the block or author a tag, and a closing tag is never truncated.
+ */
+import type { MemoryScopeRef, MemoryTruthRow } from '@jungjaehoon/mama-core/memory/types';
+export interface LearningContextInput {
+    /** Same scope list the turn's envelope uses; build it with deriveMemoryScopes. */
+    scopes: MemoryScopeRef[];
+    /** Kept for the audit line; ranking is by recency (see buildLearningContext). */
+    query: string;
+    /** Bounded reads. `query: ''` returns everything in scope. */
+    readClaims: (input: {
+        scopes: MemoryScopeRef[];
+        query: string;
+    }) => Promise<MemoryTruthRow[]>;
+    limits?: {
+        maxLessons?: number;
+        maxSummaryChars?: number;
+        maxTotalChars?: number;
+    };
+}
+export interface LearningContext {
+    /** Ready-to-append prompt text. Empty string when nothing qualifies. */
+    promptBlock: string;
+    policyIds: string[];
+    lessonIds: string[];
+    /** For the daemon.log prompt-audit line the acceptance test reads. */
+    audit: {
+        policyCount: number;
+        lessonCount: number;
+        renderedChars: number;
+    };
+}
+export declare const POLICY_TOPIC_PREFIX = "policy:";
+export declare const LESSON_TOPIC_PREFIX = "lesson:";
+/** Topics the host owns: only the turn observer writes them (gateway refuses the agent). */
+export declare function isLearningTopic(topic: unknown): boolean;
+/** Owner text is data inside a trusted block: it must not be able to author markup. */
+export declare function escapePromptMarkup(text: string): string;
+export declare function buildLearningContext(input: LearningContextInput): Promise<LearningContext>;
+/** One prompt-audit line per turn; the installed acceptance test greps it. */
+export declare function formatLearningAuditLine(turn: string, channelScopeId: string | null, context: LearningContext): string;
+//# sourceMappingURL=learning-context.d.ts.map

package/dist/operator/learning-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-context.d.ts","sourceRoot":"","sources":["../../src/operator/learning-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAE1F,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,UAAU,EAAE,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC9F,MAAM,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpF;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,sEAAsE;IACtE,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5E;AAED,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAC7C,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMvD;AAMD,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvD;AAuFD,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkDhG;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GAAG,IAAI,EAC7B,OAAO,EAAE,eAAe,GACvB,MAAM,CAER"}

package/dist/operator/learning-context.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LESSON_TOPIC_PREFIX = exports.POLICY_TOPIC_PREFIX = void 0;
+exports.isLearningTopic = isLearningTopic;
+exports.escapePromptMarkup = escapePromptMarkup;
+exports.buildLearningContext = buildLearningContext;
+exports.formatLearningAuditLine = formatLearningAuditLine;
+exports.POLICY_TOPIC_PREFIX = 'policy:';
+exports.LESSON_TOPIC_PREFIX = 'lesson:';
+/** Topics the host owns: only the turn observer writes them (gateway refuses the agent). */
+function isLearningTopic(topic) {
+    return (typeof topic === 'string' &&
+        (topic.trimStart().toLowerCase().startsWith(exports.POLICY_TOPIC_PREFIX) ||
+            topic.trimStart().toLowerCase().startsWith(exports.LESSON_TOPIC_PREFIX)));
+}
+const DEFAULT_LIMITS = { maxLessons: 3, maxSummaryChars: 240, maxTotalChars: 2400 };
+const POLICY_INSTRUCTION = 'Owner policy, in force. Apply it. The host still enforces revisions, receipts and destinations.';
+const LESSON_INSTRUCTION = 'Use as lessons, not facts; verify with the packet.';
+/** Owner text is data inside a trusted block: it must not be able to author markup. */
+function escapePromptMarkup(text) {
+    return text
+        .replace(/&(?!amp;|lt;|gt;|quot;|apos;)/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/** Ported gate: never render a half-formed row. */
+function renderable(row) {
+    if (typeof row.effective_summary !== 'string' || row.effective_summary.trim() === '') {
+        return false;
+    }
+    if (!Array.isArray(row.scope_refs)) {
+        return false;
+    }
+    if (!row.scope_refs.some((scope) => scope.kind === 'project')) {
+        return false;
+    }
+    return typeof row.updated_at === 'number' || typeof row.created_at === 'number';
+}
+/**
+ * A turn may carry more than one channel scope (a board reconcile carries the synthetic
+ * worker channel AND the channel it judges); a row matches when it names ANY of them.
+ */
+function hasChannelScope(row, turnChannels) {
+    return row.scope_refs.some((scope) => scope.kind === 'channel' && turnChannels.has(scope.id));
+}
+/** A policy applies when it names no channel (project- or global-wide) or one of this turn's. */
+function policyScopeMatches(row, turnChannels) {
+    const channels = row.scope_refs.filter((scope) => scope.kind === 'channel');
+    if (channels.length === 0) {
+        return true;
+    }
+    return hasChannelScope(row, turnChannels);
+}
+function recency(row) {
+    return row.updated_at ?? row.created_at ?? 0;
+}
+/** One line per row: a newline in stored text could forge a section heading, so it is collapsed. */
+function renderLine(row, prefix, maxSummaryChars) {
+    const name = escapePromptMarkup(row.topic.slice(prefix.length).replace(/\s+/g, ' ').trim() || 'untitled');
+    const summary = escapePromptMarkup(row.effective_summary.replace(/\s+/g, ' ').trim().slice(0, maxSummaryChars));
+    return `- ${name}: ${summary}`;
+}
+/**
+ * Budget each line against the remaining chars and drop whole lines; never slice the
+ * assembled string. Returns the block and the rows that made it in.
+ */
+function renderBlock(tag, instruction, rows, prefix, maxSummaryChars, budget) {
+    if (rows.length === 0) {
+        return { block: '', rendered: [] };
+    }
+    const open = `<${tag}>`;
+    const close = `</${tag}>`;
+    const frame = open.length + 1 + instruction.length + 1 + close.length;
+    if (frame > budget) {
+        return { block: '', rendered: [] };
+    }
+    let used = frame;
+    const lines = [];
+    const rendered = [];
+    for (const row of rows) {
+        const line = renderLine(row, prefix, maxSummaryChars);
+        if (used + line.length + 1 > budget) {
+            continue;
+        }
+        used += line.length + 1;
+        lines.push(line);
+        rendered.push(row);
+    }
+    if (lines.length === 0) {
+        return { block: '', rendered: [] };
+    }
+    return { block: [open, instruction, ...lines, close].join('\n'), rendered };
+}
+async function buildLearningContext(input) {
+    const limits = { ...DEFAULT_LIMITS, ...(input.limits ?? {}) };
+    const turnChannels = new Set(input.scopes.filter((scope) => scope.kind === 'channel').map((scope) => scope.id));
+    // ONE read with an empty query: it returns every active row in scope, which is a superset
+    // of what a ranked lesson read would return, and queryRelevantTruth has no LIMIT - a second
+    // scan of the same rows bought nothing. Lessons are channel-bound and few; recency ranks them.
+    const rows = await input.readClaims({ scopes: input.scopes, query: '' });
+    const policies = rows
+        .filter((row) => row.topic.startsWith(exports.POLICY_TOPIC_PREFIX) && renderable(row))
+        .filter((row) => policyScopeMatches(row, turnChannels))
+        .sort((a, b) => recency(b) - recency(a));
+    const lessons = rows
+        .filter((row) => row.topic.startsWith(exports.LESSON_TOPIC_PREFIX) && renderable(row))
+        .filter((row) => hasChannelScope(row, turnChannels))
+        .sort((a, b) => recency(b) - recency(a))
+        .slice(0, limits.maxLessons);
+    const policyBlock = renderBlock('policy', POLICY_INSTRUCTION, policies, exports.POLICY_TOPIC_PREFIX, limits.maxSummaryChars, limits.maxTotalChars);
+    const remaining = limits.maxTotalChars - (policyBlock.block ? policyBlock.block.length + 2 : 0);
+    const lessonBlock = renderBlock('lessons', LESSON_INSTRUCTION, lessons, exports.LESSON_TOPIC_PREFIX, limits.maxSummaryChars, remaining);
+    const promptBlock = [policyBlock.block, lessonBlock.block].filter(Boolean).join('\n\n');
+    return {
+        promptBlock,
+        policyIds: policyBlock.rendered.map((row) => row.memory_id),
+        lessonIds: lessonBlock.rendered.map((row) => row.memory_id),
+        audit: {
+            policyCount: policyBlock.rendered.length,
+            lessonCount: lessonBlock.rendered.length,
+            renderedChars: promptBlock.length,
+        },
+    };
+}
+/** One prompt-audit line per turn; the installed acceptance test greps it. */
+function formatLearningAuditLine(turn, channelScopeId, context) {
+    return `[learning] turn=${turn} channel=${channelScopeId ?? '-'} policyIds=[${context.policyIds.join(',')}] lessonIds=[${context.lessonIds.join(',')}] chars=${context.audit.renderedChars}`;
+}
+//# sourceMappingURL=learning-context.js.map

package/dist/operator/learning-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-context.js","sourceRoot":"","sources":["../../src/operator/learning-context.ts"],"names":[],"mappings":"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"}

package/dist/operator/learning-markers.d.ts

@@ -0,0 +1,19 @@
+export interface LearningMarkerConfig {
+    durableRule: string[];
+    correction: string[];
+    oneOffVeto: string[];
+    topicNouns: Record<string, string[]>;
+}
+export declare const DEFAULT_LEARNING_MARKERS: LearningMarkerConfig;
+export interface DurableInstruction {
+    kind: 'policy' | 'lesson' | 'none';
+    topicNoun?: string;
+    matchedMarkers: string[];
+    /** Why it was or was not classified; goes into the audit log. */
+    reason: string;
+}
+export declare function learningMarkersPath(env?: NodeJS.ProcessEnv): string;
+/** Defaults merged with the owner's overrides; overrides ADD to a list, never replace it. */
+export declare function loadLearningMarkers(env?: NodeJS.ProcessEnv): LearningMarkerConfig;
+export declare function detectDurableInstruction(text: string, cfg?: LearningMarkerConfig): DurableInstruction;
+//# sourceMappingURL=learning-markers.d.ts.map

package/dist/operator/learning-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-markers.d.ts","sourceRoot":"","sources":["../../src/operator/learning-markers.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACtC;AAED,eAAO,MAAM,wBAAwB,EAAE,oBAUtC,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEhF;AAUD,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,oBAAoB,CA2C9F;AAyBD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,oBAA+C,GACnD,kBAAkB,CA0CpB"}