@staix/agent-mem 0.22.1 → 0.23.0

package/src/memory/capture.ts

@@ -4,7 +4,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { looksSecret } from "./screen.ts";
-import { captureAttribution, normalizeCaptureFields, SESSION_KEY, type CaptureFields } from "./capture-input.ts";
+import { captureAttribution, normalizeCaptureFields, RecordNormalizationRefusal, SESSION_KEY, type CaptureFields } from "./capture-input.ts";
 export { CAPTURE_MAX_EXCERPT, CAPTURE_MAX_PATHS } from "./capture-input.ts";
 import { memoryBase } from "./home.ts";
 import { captureShardDir, ensureShardDescriptor, readShardDescriptor, resolveAlias, shardKeyHash } from "./shard.ts";
@@ -292,6 +292,7 @@ export class CaptureStore {
       // #173: additive nullable columns. Older readers use explicit or `SELECT *` column names and ignore extras.
       addAttributionColumns(db);
       this.ensureBriefSummaryIndex(true);
+      this.ensureBriefRecordIndex(true);
       this.ensureFts();
     } catch (error) {
       if (!lockError(error)) { db.close(); throw error; }
@@ -390,7 +391,7 @@ export class CaptureStore {
   private briefReady = false;
   private prepareBriefSummaryIndex(): void {
     if (this.readOnly || this.briefReady) return;
-    try { this.ensureBriefSummaryIndex(false); this.briefReady = true; }
+    try { this.ensureBriefSummaryIndex(false); this.ensureBriefRecordIndex(false); this.briefReady = true; }
     catch { /* Optional summary coverage remains partial; query engines remain independent. */ }
   }
   /** One-time MCP read cost only: hooks neither create this derived index nor scan history to fill it. */
@@ -437,6 +438,11 @@ export class CaptureStore {
     const receipt = options.receipt;
     if (receipt !== undefined && (typeof receipt !== "string" || !/^[a-f0-9]{64}$/.test(receipt) || input.at === undefined)) throw new Error("capture receipt needs a stable time and a 64-hex digest");
     const row = this.normalize(input);
+    // Pending hook Records must stay whole when caps or screening change before replay.
+    // Check before receipt derivation or any spool/DB write; drainers retire this policy refusal whole.
+    if (input.event === "Record" && (row.excerpt !== input.excerpt || JSON.stringify(row.paths) !== JSON.stringify(input.paths ?? []))) {
+      throw new RecordNormalizationRefusal();
+    }
     // Reuse the immutable spool format and its existing unique index: a crash between capture and cursor
     // advance replays exactly the same screened line, whether first written directly or under contention.
     const spoolId = receipt === undefined ? null : createHash("sha256").update(this.spoolLine(row, receipt)).digest("hex");
@@ -661,6 +667,40 @@ export class CaptureStore {
     if (bounded) this.db.transaction(build).immediate(); else build();
   }
 
+  /** Share the summary index's atomic small-store and off-hook preparation rules. */
+  private ensureBriefRecordIndex(bounded: boolean): void {
+    if (this.db.query("SELECT 1 FROM sqlite_master WHERE name='rows_brief_records_v1' AND type='index'").get()) return;
+    const build = () => {
+      if (bounded) {
+        const count = (this.db.query("SELECT COUNT(*) AS n FROM (SELECT 1 FROM rows LIMIT 129)").get() as { n: number }).n;
+        if (count > 128) return;
+      }
+      this.db.run("CREATE INDEX IF NOT EXISTS rows_brief_records_v1 ON rows(project,at,id) WHERE event='Record' AND (subagent IS NULL OR subagent != 1)");
+    };
+    if (bounded) this.db.transaction(build).immediate(); else build();
+  }
+
+  /** A separate derived index leaves the released summary predicate unchanged. */
+  readBriefRecords(limit = BRIEF_SUMMARY_CANDIDATES): { rows: CaptureRow[]; partial: boolean } {
+    this.checkReadBinding();
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > BRIEF_SUMMARY_CANDIDATES) throw new Error("invalid brief Record limit; use an integer from 1 to 32");
+    const indexed = !!this.db.query("SELECT 1 FROM sqlite_master WHERE name='rows_brief_records_v1' AND type='index'").get();
+    let rows: RawRow[], partial = false;
+    if (indexed) {
+      rows = this.db.query("SELECT * FROM rows INDEXED BY rows_brief_records_v1 WHERE project=? AND event='Record' AND (subagent IS NULL OR subagent != 1) ORDER BY at DESC,id DESC LIMIT ?")
+        .all(this.key, limit + 1) as RawRow[];
+    } else {
+      // ponytail: inspect only 128 recent legacy rows until off-hook search prepares
+      // the index; an explicit bounded index-preparation command is the upgrade.
+      const hasSubagent = (this.db.query("PRAGMA table_info(rows)").all() as { name: string }[]).some(column => column.name === "subagent");
+      const subagent = hasSubagent ? " AND (subagent IS NULL OR subagent != 1)" : "";
+      rows = this.db.query(`SELECT * FROM (SELECT * FROM rows INDEXED BY rows_at ORDER BY at DESC,id DESC LIMIT 128) WHERE project=? AND event='Record'${subagent} ORDER BY at DESC,id DESC LIMIT ?`)
+        .all(this.key, limit + 1) as RawRow[];
+      partial = this.db.query("SELECT id FROM rows INDEXED BY rows_at ORDER BY at DESC,id DESC LIMIT 129").all().length > 128;
+    }
+    return { rows: rows.slice(0, limit).map(toRow), partial: partial || rows.length > limit };
+  }
+
   /** Index reads return at most33 bodies. Legacy fallback reads at most128 recent rows. */
   readBriefSummaries(limit = BRIEF_SUMMARY_CANDIDATES): { rows: CaptureRow[]; partial: boolean } {
     this.checkReadBinding();

package/src/memory/config.ts

@@ -17,10 +17,12 @@ export const CONFIG_FILE = "amem.config.json";
 export const REPO_CONFIG_DIR = ".amem";
 export const REPO_CONFIG_FILE = "config";
 const MAX_CONFIG_BYTES = 64 * 1024;
-const MACHINE_KEYS = ["home", "denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths", "capture"] as const;
-const REPO_KEYS = ["denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths"] as const;
+const MACHINE_KEYS = ["home", "denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths", "capture", "records"] as const;
+const REPO_KEYS = ["denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths", "records"] as const;
 
 export interface AmemConfig {
+  /** Static SessionStart record instruction; absent means enabled. Repository false only narrows. */
+  records?: boolean;
   /** The memory home, when the file moves it (a pointer file: see `configuredHome`). `AMEM_HOME` still wins. Machine file only. */
   home?: string;
   denyPaths: string[];
@@ -77,6 +79,10 @@ function parseFile(raw: unknown, label: string, keys: readonly string[]): Partia
   const out: Partial<AmemConfig> & { capture?: AmemConfig["capture"] } = {
     denyPaths: listOf(body.denyPaths, "denyPaths", label), piiPatterns: listOf(body.piiPatterns, "piiPatterns", label),
   };
+  if (Object.hasOwn(body, "records")) {
+    if (typeof body.records !== "boolean") return fail(label, "records is not a boolean");
+    out.records = body.records;
+  }
   const briefBytes = countOf(body.briefBytes, "briefBytes", label, 1_000_000); if (briefBytes !== undefined) out.briefBytes = briefBytes;
   const excerptBytes = countOf(body.excerptBytes, "excerptBytes", label, 100_000); if (excerptBytes !== undefined) out.excerptBytes = excerptBytes;
   const capturePaths = countOf(body.capturePaths, "capturePaths", label, 1000); if (capturePaths !== undefined) out.capturePaths = capturePaths;
@@ -149,6 +155,7 @@ export function loadAmemConfig(base: string, repoRoot?: string): LoadedConfig {
   if (piiPatterns.length > 64) fail(machinePath, "piiPatterns and the repository's piiPatterns name more than 64 entries together");
   const config: AmemConfig = { denyPaths, piiPatterns, capture: { ...(machine?.capture ?? {}) } };
   if (machine?.home !== undefined) config.home = machine.home;
+  if (machine?.records !== undefined || repo?.records !== undefined) config.records = machine?.records !== false && repo?.records !== false;
   for (const key of ["briefBytes", "excerptBytes", "capturePaths"] as const) { const value = lower(machine?.[key], repo?.[key]); if (value !== undefined) config[key] = value; }
   return { config, source: { machine: machineRaw === undefined ? null : machinePath, repo: repoPath } };
 }

package/src/memory/metrics.ts

@@ -1,10 +1,11 @@
 import { closeSync, constants, fstatSync, openSync, readSync, appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import type { RecordDropReason } from "../hook-record.ts";
 import type { HookRssSources } from "../hook-resources.ts";
 import type { HookTranscriptStopReason } from "../hook-contract.ts";
 import { join } from "node:path";
 
 /** Rolling resource samples; importing this leaf never loads a memory store or capacity probe. */
-export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; rssSources?: HookRssSources; rssScope?: "owned-images"; transcriptOffset?: number; transcriptStopReason?: HookTranscriptStopReason; /** #226: owned children killed but still alive when the hook returned (bounded reap). */ abandonedChildren?: number; /** #226: a killed worker skipped this call's drain; staged records stay pending (not a capture drop). */ drainSkipped?: number; /** #226: when the worker drain started (ms after hook start) and how many records it committed. */ drainStartMs?: number; drained?: number; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; rssSources?: HookRssSources; rssScope?: "owned-images"; transcriptOffset?: number; transcriptStopReason?: HookTranscriptStopReason; /** #226: owned children killed but still alive when the hook returned (bounded reap). */ abandonedChildren?: number; /** #226: a killed worker skipped this call's drain; staged records stay pending (not a capture drop). */ drainSkipped?: number; /** #226: when the worker drain started (ms after hook start) and how many records it committed. */ drainStartMs?: number; drained?: number; idleMB?: number; recordInstructionBytes?: number; recordInstructionEstimatedTokens?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
 const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
 
 export function metricsPath(base: string): string {
@@ -38,8 +39,8 @@ export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[]
 }
 
 
-export type CaptureDropReason = "summary_capacity" | "scope_capacity" | "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired" | "transcript_line_bound";
-const DROP_REASONS: readonly CaptureDropReason[] = ["summary_capacity", "scope_capacity", "spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired", "transcript_line_bound"];
+export type CaptureDropReason = "summary_capacity" | "scope_capacity" | "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired" | "transcript_line_bound" | RecordDropReason;
+const DROP_REASONS: readonly CaptureDropReason[] = ["summary_capacity", "scope_capacity", "spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired", "transcript_line_bound", "record_invalid", "record_count", "record_length", "record_policy", "record_identity", "record_timestamp"];
 /** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. Fails open to no counts: hooks never deny over metrics. */
 export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
   const read = readCaptureDrops(base);

package/src/memory/private-spans.ts

@@ -9,17 +9,20 @@
  */
 const TAG = /<\s*(\/?)\s*private(?=[\s/>])[^<>]*>/gi;
 
-export function stripPrivateSpans(text: string): string {
+/** The optional range observer receives only omitted offsets, never private text. */
+export function stripPrivateSpans(text: string, omitted?: (start: number, end: number) => void): string {
   if (!/<\s*\/?\s*private(?=[\s/>])/i.test(text)) return text;
-  let out = "", depth = 0, last = 0, match: RegExpExecArray | null;
+  let out = "", depth = 0, last = 0, privateStart = 0, match: RegExpExecArray | null;
   TAG.lastIndex = 0;
   while ((match = TAG.exec(text))) {
     const closing = match[1] === "/", stray = closing && depth === 0;
     if (depth === 0) out += text.slice(last, stray ? match.index + match[0].length : match.index);   // a stray closer is plain text: keep it
-    if (closing) { if (depth > 0) depth--; } else depth++;
+    if (closing) { if (depth > 0 && --depth === 0) omitted?.(privateStart, match.index + match[0].length); }
+    else { if (depth === 0) privateStart = match.index; depth++; }
     last = match.index + match[0].length;
   }
   if (depth === 0) out += text.slice(last);
+  else omitted?.(privateStart, text.length);
   return out;
 }
 

package/src/memory/repo-scope.ts

@@ -284,8 +284,14 @@ export function namesPrivatePath(text: string): boolean {
   return HOME_PATH.some(re => re.test(folded)) || (home.length > 3 && folded.includes(home));
 }
 const SAFE_NODE = /^(?:path|symbol|issue):/;
-/** A graph node that may be committed: a repository-relative path or symbol, or an issue. Private task, goal and memory references and absolute or escaping paths stay out. */
+// Offline syntax only (#185): no lookup. DOI `10.<registrant>/<suffix>` with printable, space-free ASCII suffix; arXiv new (`YYMM.NNNN[N]`) and old (`archive[.XX]/YYMMNNN`) ids, optional `vN`.
+const DOI_NODE = /^doi:10\.\d{4,9}(?:\.\d+)*\/[\x21-\x7e]+$/;
+const ARXIV_NODE = /^arxiv:(?:\d{2}(?:0[1-9]|1[0-2])\.\d{4,5}|[a-z]+(?:-[a-z]+)*(?:\.[A-Z]{2})?\/\d{2}(?:0[1-9]|1[0-2])\d{3})(?:v[1-9]\d*)?$/;
+/** A public literature identifier (`doi:` or `arxiv:`) that is well formed and so may be committed to repo scope. */
+export function publicIdentifierNode(node: string): boolean { return DOI_NODE.test(node) || ARXIV_NODE.test(node); }
+/** A graph node that may be committed: a repository-relative path or symbol, an issue, or a well-formed public `doi:`/`arxiv:` identifier. Private task, goal, memory and host-local (`run:`) references, malformed identifiers and absolute or escaping paths stay out. */
 function committableNode(node: string): boolean {
+  if (node.startsWith("doi:") || node.startsWith("arxiv:")) return publicIdentifierNode(node);
   if (!SAFE_NODE.test(node)) return false;
   const where = node.startsWith("path:") ? node.slice(5) : node.startsWith("symbol:") && node.includes("@") ? node.slice(node.lastIndexOf("@") + 1) : "";
   if (!where) return !node.startsWith("path:") && !node.startsWith("symbol:");

package/src/memory/search-score.ts

@@ -14,16 +14,18 @@ type ScoreExpr = { op: "rank" | "tier" | "age" } | { op: "constant"; value: numb
 const MONTH_DAYS = 30;
 const TIER_WEIGHTS: Readonly<Record<string, number>> = { long: 1, capture: 0.5 };
 const DEFAULT_TIER_WEIGHT = 0.9;
-// ponytail: fixed 1.25x ceiling for conversational capture, not a learned relevance model.
+// ponytail: fixed 1.25x conversation and 1.5x Record weights, not a learned relevance model.
 // Raise it only with fresh S/M no-loss and private-capture evidence; curated tier factors stay unchanged.
 export const CAPTURE_CONVERSATION_WEIGHT = 1.25;
+const CAPTURE_RECORD_WEIGHT = 1.5;
 const CONVERSATIONAL_CAPTURE_EVENTS = ["Stop", "UserPromptSubmit", "Title", "Recap", "Compact"] as const;
 export function captureEventWeight(event: string): number {
+  if (event === "Record") return CAPTURE_RECORD_WEIGHT;
   return (CONVERSATIONAL_CAPTURE_EVENTS as readonly string[]).includes(event) ? CAPTURE_CONVERSATION_WEIGHT : 1;
 }
 /** Only fixed internal SQL identifiers are supplied by callers; event values remain stored data. */
 export function captureEventWeightSql(eventColumn: string): string {
-  return `(CASE WHEN ${eventColumn} IN (${CONVERSATIONAL_CAPTURE_EVENTS.map(event => `'${event}'`).join(", ")}) THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
+  return `(CASE WHEN ${eventColumn} = 'Record' THEN ${CAPTURE_RECORD_WEIGHT} WHEN ${eventColumn} IN (${CONVERSATIONAL_CAPTURE_EVENTS.map(event => `'${event}'`).join(", ")}) THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
 }
 const TIER_FACTOR: ScoreExpr = { op: "tier" };
 const DENOMINATOR: ScoreExpr = { op: "add", left: { op: "constant", value: 1 }, right: { op: "max", left: { op: "constant", value: 0 }, right: { op: "age" } } };

package/src/memory/sync-placement-prerequisites.ts

@@ -9,6 +9,13 @@ import { PLACEMENT_PROFILE_SCHEMA, validatePlacementBaseV2, type PlacementBaseV2
 
 export const PLACEMENT_ACTIVATION_MIN_READER = "0.21.0";
 const preview = "amem migrate --sync-placement --dry-run";
+/** Typed only for safe adapter diagnostics; the floor predicate and remedy stay shared. */
+export class PlacementHomeFloorError extends Error {
+  constructor(minReader: string) {
+    super(`Sync placement requires a person-authored home floor of ${minReader} or later in formats.json; have the person append that record, then rerun ${preview}.`);
+    this.name = "PlacementHomeFloorError";
+  }
+}
 function requireHomeFloor(home: string,minReader:string): string {
   assertFormatFloor(home, "curated"); assertFormatFloor(home, "sync");
   const floors = readFormatFloors(home), minimum = minReader.split(".").map(Number);
@@ -18,7 +25,7 @@ function requireHomeFloor(home: string,minReader:string): string {
     for (let i = 0; i < 3; i++) if (parts[i] !== minimum[i]) return parts[i]! > minimum[i]!;
     return true;
   });
-  if (!adequate) throw Error(`Sync placement requires a person-authored home floor of ${minReader} or later in formats.json; have the person append that record, then rerun ${preview}.`);
+  if (!adequate) throw new PlacementHomeFloorError(minReader);
   return hashJSON(floors);
 }
 export function requirePlacementHomeFloor(home:string):string{return requireHomeFloor(home,PLACEMENT_ACTIVATION_MIN_READER);}

package/src/session-brief-worker.ts

@@ -121,7 +121,7 @@ if (import.meta.main) {
         else try {
           const { scanHookTranscriptTail } = await import("./hook-transcript.ts");
           const scanned = await scanHookTranscriptTail(scan.transcript, {
-            cwd: scan.cwd, base: scan.base, policy: scan.policy, deadline: performance.now() + (scanEnd - now()),
+            cwd: scan.cwd, base: scan.base, policy: scan.policy, workBudgetMs: 60, deadline: performance.now() + (scanEnd - now()),
             // Same existing oldest-first drain and one shared budget, never a new 32-file allowance per publication.
             onPublication: async () => { await replay(scanEnd, false); },
             onBackpressure: () => replay(scanEnd, false),

package/src/session-brief.ts

@@ -1,6 +1,7 @@
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { CaptureRow } from "./memory/capture.ts";
+import { parseRecordLines } from "./hook-record.ts";
 import { readSelector } from "./memory/generation.ts";
 import { memoryHome } from "./memory/home.ts";
 import { canonicalPath, realPath } from "./memory/platform.ts";
@@ -99,6 +100,14 @@ function captureDisplay(row: CaptureRow): { data: unknown; partial: boolean } {
     partial: excerpt.partial || event.partial || row.paths.length > paths.length || paths.some(path => path.partial) };
 }
 
+/** Keep the canonical Record whole; '-' is valid only for project-bound decisions/contracts. */
+function recordDisplay(row: CaptureRow): { data: unknown; partial: boolean } | undefined {
+  const parsed = parseRecordLines(row.excerpt), record = parsed.records[0];
+  if (!record || parsed.records.length !== 1 || Object.keys(parsed.drops).length || record.line !== row.excerpt
+    || JSON.stringify(record.anchors) !== JSON.stringify(row.paths)) return;
+  return { data: { event: "Record", paths: record.anchors, excerpt: record.line }, partial: false };
+}
+
 /** A short-lived, model-free projection. The hook host supplies the hard process deadline; this function owns no timer or child. */
 export async function sessionStartBrief(options: BriefOptions): Promise<BriefResult> {
   let result = unavailable();
@@ -204,6 +213,8 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
             if (section === "capture" && skipCaptureIds.has((row as { id: number }).id)) continue;
             // #173: subagent capture stays searchable but never enters the session brief.
             if (section === "capture" && (row as { subagent?: unknown }).subagent === true) continue;
+            // Records have their own five-row, whole-line selection before raw captures.
+            if (section === "capture" && (row as { event?: unknown }).event === "Record") continue;
             if (!await screen(row)) continue;
             if (selected++ >= SECTION_RECORDS) { coverage[section] = "partial"; return; }
             await add(section, display(row), section === "curated");
@@ -250,6 +261,16 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
         }
         const capture = new CaptureStore({ memoryDir: base, project, cwd, ...(options.nativeSession || options.measureOnly ? { readOnly: true, busyTimeoutMs: options.measureOnly ? 1000 : 0, maxReadRows: 128, recentReadRows: true } : {}) }); closers.push(() => capture.close());
         if (capture.recentReadTruncated) coverage.capture = "partial";
+        const records = capture.readBriefRecords();
+        if (records.partial) coverage.capture = "partial";
+        let selectedRecords = 0;
+        for (const row of records.rows) {
+          if (row.project !== project || row.subagent === true) continue;
+          if (selectedRecords >= 5) { coverage.capture = "partial"; break; }
+          if (!await screen(row)) continue;
+          const shown = recordDisplay(row);
+          if (shown && await add("capture", shown, false)) selectedRecords++;
+        }
         const summaries = capture.readBriefSummaries(), summaryIds = new Set<number>();
         if (summaries.partial) coverage.capture = "partial";
         let selectedSummaries = 0;

package/src/sync-placement-writer-context.ts

@@ -1,15 +1,17 @@
-/** CLI adapter only. Expected locators are never returned as fresh writer facts. */
+/** CLI/host adapter. Expected locators are never returned as fresh writer facts. */
 import { types } from "node:util";
-import { realPath } from "./memory/platform.ts";
+import { fileURLToPath } from "node:url";
+import { canonicalPath, realPath } from "./memory/platform.ts";
 import { canonicalJSON } from "./memory/generation.ts";
 import { readSetupWriterRoots } from "./setup.ts";
 import { measureSyncPlacementWriters, extractSyncPlacementWriterFailure, type SyncPlacementWriterFailureDetail, type SyncPlacementWriterMeasurement } from "./memory/sync-placement-writers.ts";
 import { readEffectiveSyncPlacementWriters } from "./memory/sync-placement-effective-writers.ts";
-import { requirePlacementHomeFloor } from "./memory/sync-placement-prerequisites.ts";
+import { PlacementHomeFloorError, requirePlacementHomeFloor } from "./memory/sync-placement-prerequisites.ts";
+import { FormatFloorError } from "./memory/formats.ts";
 import type { PlacementCapturePort } from "./memory/sync-placement-capture.ts";
 import { SharedWriterRevisionError } from "./memory/sync-placement-writer-revision-format.ts";
 
-export type PlacementWriterRootCategory = "running CLI" | "setup receipt" | "declared writer" | "active locator" | "home floor" | "writer renewal";
+export type PlacementWriterRootCategory = "running CLI" | "host package" | "setup receipt" | "declared writer" | "active locator" | "home floor" | "writer renewal";
 export type PlacementWriterContextPhase = "initial" | "active";
 const failureDetails:Record<SyncPlacementWriterFailureDetail,string>={
   "below-minimum":"release is below 0.21.0", "wrong-package":"package is not @staix/agent-mem", "writable-runtime":"runtime code is group- or world-writable", unreadable:"runtime files are unreadable or missing",
@@ -30,11 +32,12 @@ export class PlacementWriterContextError extends Error {
   }
 }
 function safeRefusal(error: unknown, category: PlacementWriterRootCategory,phase:PlacementWriterContextPhase="active"): PlacementWriterContextError {
+  if (error && typeof error === "object" && !types.isProxy(error) && (error instanceof PlacementHomeFloorError || error instanceof FormatFloorError)) return new PlacementWriterContextError("home floor","unavailable",phase);
   if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SharedWriterRevisionError){const code=Object.getOwnPropertyDescriptor(error,"code")?.value;if(code==="pending"||code==="staging")return new PlacementWriterContextError("writer renewal","unavailable",phase,undefined,code);}
   if (error && typeof error === "object" && !types.isProxy(error) && error instanceof PlacementWriterContextError) {
     const fields=Object.getOwnPropertyDescriptors(error),root=fields.category,cause=fields.causeClass,detail=fields.detail;
     const category:unknown=root&&"value"in root?root.value:undefined,causeClass:unknown=cause&&"value"in cause?cause.value:undefined;
-    if (typeof category==="string" && ["running CLI","setup receipt","declared writer","active locator","home floor","writer renewal"].includes(category)
+    if (typeof category==="string" && ["running CLI","host package","setup receipt","declared writer","active locator","home floor","writer renewal"].includes(category)
       && typeof causeClass==="string" && ["missing","changed","unavailable"].includes(causeClass)) {
       const ownDetail=detail&&"value"in detail&&typeof detail.value==="string"&&Object.hasOwn(failureDetails,detail.value)?detail.value as SyncPlacementWriterFailureDetail:undefined;
       const state=fields.renewalState?.value;
@@ -93,8 +96,9 @@ export function initialPlacementWriterContext(home: string, roots: readonly stri
 /** Active callbacks re-read the bound locator AND measure every package anew. No activation or renewal occurs. */
 export function activePlacementWriterContext(home: string, ownRoot: string): PlacementWriterContext {
   const read = () => {
-    requirePlacementHomeFloor(home);
-    const effective=readEffectiveSyncPlacementWriters(home);
+    try { requirePlacementHomeFloor(home); } catch (error) { throw safeRefusal(error,"home floor"); }
+    let effective: ReturnType<typeof readEffectiveSyncPlacementWriters>;
+    try { effective=readEffectiveSyncPlacementWriters(home); } catch (error) { throw safeRefusal(error,"active locator"); }
     const roots=effective.roots;if(!roots)return fail("active locator","unavailable");
     const needed = required(home,ownRoot);
     if(!roots.includes(needed.own))return fail("running CLI","missing");
@@ -113,6 +117,26 @@ export function activePlacementWriterContext(home: string, ownRoot: string): Pla
   } }; return context;
 }
 
+/**
+ * Host sync port bound to this executing installation, never a caller-selected root.
+ * Legacy sync ignores the lazy port. Each invoked v3 check re-reads all expected
+ * inventory and measures every root again; the cached context is not fresh proof.
+ */
+export function createPlacementAttestation(home: string): PlacementCapturePort["attest"] {
+  const base = canonicalPath(home), ownRoot = fileURLToPath(new URL("..", import.meta.url));
+  let context: PlacementWriterContext | undefined;
+  return () => {
+    try {
+      context ??= activePlacementWriterContext(base, ownRoot);
+      return context.attest();
+    } catch (error) {
+      const refusal = safeRefusal(error, "active locator");
+      if (refusal.category === "running CLI") throw new PlacementWriterContextError("host package", refusal.causeClass, refusal.phase, refusal.detail, refusal.renewalState);
+      throw refusal;
+    }
+  };
+}
+
 /** Person preview only: incomplete measurements remain explicit and never become an attestation. */
 export function previewActivePlacementWriters(home: string, ownRoot: string, requested: readonly string[] = []) {
   const effective=readEffectiveSyncPlacementWriters(home),mapped=effective.roots;if(!mapped)return fail("active locator","unavailable");