@tpsdev-ai/flair 0.19.0 → 0.20.1

package/dist/cli.js

@@ -6648,6 +6648,11 @@ program
     .option("--no-restart", "Do not restart the component after deploy (default: restart=true)")
     .option("--dry-run", "Resolve package, validate args, skip the deploy call")
     .option("--package-root <dir>", "Override package root (mainly for testing)")
+    .option("--deployment-timeout <ms>", "Milliseconds harper waits for cluster-wide peer replication (env: FABRIC_DEPLOYMENT_TIMEOUT; default: 600000 — harper's own 120s default is too short for Fabric)")
+    .option("--install-timeout <ms>", "Milliseconds harper waits for package install (env: FABRIC_INSTALL_TIMEOUT; default: 600000)")
+    .option("--no-verify", "Skip post-deploy served-API verification (default: verify — on by design, so the CLI can't report success on an empty/broken deploy)")
+    .option("--verify-timeout <ms>", "Milliseconds to wait for the served API to settle after harper's post-deploy restart before verifying (default: 300000)")
+    .option("--verify-resource <name>", "Resource to verify is serving after deploy (repeatable; default: derived from the deployed package's dist/resources)", (val, prev) => [...prev, val], [])
     .action(async (opts) => {
     const green = (s) => `\x1b[32m${s}\x1b[0m`;
     const red = (s) => `\x1b[31m${s}\x1b[0m`;
@@ -6665,6 +6670,12 @@ program
         restart: opts.restart !== false,
         dryRun: opts.dryRun ?? false,
         packageRoot: opts.packageRoot,
+        deploymentTimeoutMs: Number(opts.deploymentTimeout ?? process.env.FABRIC_DEPLOYMENT_TIMEOUT ?? 600_000),
+        installTimeoutMs: Number(opts.installTimeout ?? process.env.FABRIC_INSTALL_TIMEOUT ?? 600_000),
+        verify: opts.verify !== false,
+        verifyResources: opts.verifyResource?.length ? opts.verifyResource : undefined,
+        verifyTimeoutMs: Number(opts.verifyTimeout ?? 300_000),
+        onProgress: (msg) => console.log(dim(`  ${msg}`)),
     };
     const errors = validateDeployOptions(deployOpts);
     if (errors.length) {
@@ -6689,7 +6700,7 @@ program
             console.log(dim(`  package root: ${result.packageRoot}`));
             return;
         }
-        console.log(`\n${green("✓")} Flair ${result.version} deployed`);
+        console.log(`\n${green("✓")} Flair ${result.version} deployed${deployOpts.verify ? " and verified serving" : ""}`);
         console.log(`\n  URL:     ${result.url}`);
         console.log(`  Project: ${result.project}`);
         console.log(`\nNext steps:`);
@@ -6703,6 +6714,12 @@ program
         if (hint?.includes("401") || hint?.includes("unauthoriz")) {
             console.error(dim("  hint: check Fabric Studio → Cluster Settings → Admin for the admin password"));
         }
+        if (hint?.includes("component is not serving")) {
+            console.error(dim("  hint: harper reported success but the served API disagrees — check the Fabric Studio component logs for the real deploy error, then retry"));
+        }
+        if (hint?.includes("did not settle")) {
+            console.error(dim("  hint: Harper may still be restarting — check Fabric Studio, or retry with a longer --verify-timeout"));
+        }
         process.exit(1);
     }
 });
@@ -7123,7 +7140,7 @@ memory.command("add [content]").requiredOption("--agent <id>")
     .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content; ops-wkoh)")
     .option("--subject <text>", "one-line title / entity this memory is about")
     .option("--derived-from <csv>", "Comma-separated source Memory IDs this memory was distilled/reflected from (sets Memory.derivedFrom; used by the `rem rapid` reflection loop)")
-    .option("--visibility <value>", "Memory visibility (sets Memory.visibility). Use 'office' to share office-wide with every team agent; omit (default) to keep it private to this agent (flair#509)")
+    .option("--visibility <value>", "Writer-controlled sharing intent (sets Memory.visibility): 'private' (owner-only, never visible to a grant-holder) or 'shared' (visible to owner + any agent holding a read/search MemoryGrant). Omit to use the server's durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private (flair#509, ops-2dm3)")
     .action(async (contentArg, opts) => {
     const content = contentArg ?? opts.content;
     if (!content) {

package/dist/deploy.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 // Files that must be present in a Flair package for deployment.
@@ -11,6 +11,23 @@ export const REQUIRED_PACKAGE_FILES = [
     "ui",
     "config.yaml",
 ];
+// harper's own deploy CLI defaults to a 120s peer-replication timeout that's
+// too short for Fabric — the CLI aborts mid-replicate with no override,
+// which is exactly the incident this module now guards against. 10 minutes
+// gives cluster-wide replication + install room to actually finish.
+export const DEFAULT_DEPLOYMENT_TIMEOUT_MS = 600_000;
+export const DEFAULT_INSTALL_TIMEOUT_MS = 600_000;
+// Post-deploy verification: how long we'll wait for the served API to come
+// back up after harper's restart, how often we poll while waiting, and how
+// many consecutive reachable responses count as "settled" (a single
+// reachable probe right after restart can be a fluke mid-flap).
+export const DEFAULT_VERIFY_TIMEOUT_MS = 300_000;
+export const VERIFY_POLL_INTERVAL_MS = 15_000;
+export const VERIFY_SETTLE_STREAK = 3;
+// Fallback when dist/resources can't be scanned (e.g. an unusual package
+// layout via --package-root). Memory is Flair's original, always-present
+// resource — a reasonable single thing to check when derivation fails.
+export const FALLBACK_VERIFY_RESOURCE = "Memory";
 export function validateOptions(opts) {
     const errors = [];
     if (!opts.target) {
@@ -81,6 +98,65 @@ export function validatePackageLayout(packageRoot) {
             missing.join(", "));
     }
 }
+// Derive the list of served, table-backed REST resources from the compiled
+// package — no hardcoded resource list. Flair's jsResource files (dist/resources/*.js)
+// contain both real Resource classes (routable, GET-able) and plain helper
+// modules (embeddings, auth, scoring, etc). We only ship dist/ in the
+// published package (resources/*.ts source is not in package.json's `files`),
+// so this scans the COMPILED output, matching the convention every current
+// table-backed resource follows:
+//
+//   export class <Name> extends databases.<db>.<Name> { ... }
+//
+// i.e. the exported class name equals the filename equals the underlying
+// table name (Memory.js -> `export class Memory extends databases.flair.Memory`,
+// same for Agent, Soul, MemoryGrant, Credential, OrgEvent, etc). Helper
+// modules are lowercase-first (agent-auth.js, embeddings-provider.js, ...)
+// and never match, so they're skipped without needing a denylist. Files
+// that export a resource extending a *generic* `Resource` base (AgentCard,
+// WorkspaceLatest, action-style endpoints) are deliberately excluded here —
+// they're action/command endpoints, not GET-able collections, and asserting
+// non-404 on them would be the wrong check.
+// Literal regex (no interpolation — satisfies semgrep detect-non-literal-regexp):
+// matches `export class <Name> extends databases.<db>.<Name>` where the `\1`
+// backreference forces the class name and the table name to be identical.
+// Capture group 1 is the resource name; the caller matches it against the filename.
+const EXPORTED_TABLE_CLASS_RE = /export class (\w+) extends databases\.[A-Za-z_$][\w$]*\.\1\b/g;
+export function deriveVerifyResources(packageRoot) {
+    const resourcesDir = join(packageRoot, "dist", "resources");
+    let entries;
+    try {
+        entries = readdirSync(resourcesDir);
+    }
+    catch {
+        return [FALLBACK_VERIFY_RESOURCE];
+    }
+    const names = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".js"))
+            continue;
+        const base = entry.slice(0, -3);
+        if (!/^[A-Z]/.test(base))
+            continue; // helper modules are camelCase/lowercase
+        let src;
+        try {
+            src = readFileSync(join(resourcesDir, entry), "utf8");
+        }
+        catch {
+            continue;
+        }
+        // The file serves a table resource iff it exports a class whose name matches
+        // its filename (base) and extends databases.<db>.<sameName>.
+        for (const m of src.matchAll(EXPORTED_TABLE_CLASS_RE)) {
+            if (m[1] === base) {
+                names.push(base);
+                break;
+            }
+        }
+    }
+    names.sort();
+    return names.length ? names : [FALLBACK_VERIFY_RESOURCE];
+}
 function resolveHarperBin(packageRoot) {
     const local = join(packageRoot, "node_modules/@harperfast/harper/dist/bin/harper.js");
     if (existsSync(local))
@@ -105,6 +181,22 @@ function resolveHarperBin(packageRoot) {
     throw new Error("Could not locate Harper CLI binary (@harperfast/harper). " +
         "Flair deploy requires Harper to be installed alongside Flair.");
 }
+// Pure arg-array builder — separated from spawnHarper so the timeout
+// passthrough (and the rest of the arg shape) is unit-testable without
+// mocking child_process / actually spawning harper.
+export function buildHarperDeployArgs(opts, url, project) {
+    const deploymentTimeoutMs = opts.deploymentTimeoutMs ?? DEFAULT_DEPLOYMENT_TIMEOUT_MS;
+    const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+    return [
+        "deploy",
+        `target=${url}`,
+        `project=${project}`,
+        `restart=${opts.restart !== false}`,
+        `replicated=${opts.replicated !== false}`,
+        `deployment_timeout=${deploymentTimeoutMs}`,
+        `install_timeout=${installTimeoutMs}`,
+    ];
+}
 function spawnHarper(bin, args, cwd, env) {
     return new Promise((resolveP, rejectP) => {
         const p = spawn(process.execPath, [bin, ...args], {
@@ -121,6 +213,85 @@ function spawnHarper(bin, args, cwd, env) {
         });
     });
 }
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// A single reachability probe against the served (REST) base URL. Harper
+// restarts the process after every deploy, so the endpoint FLAPS for a bit —
+// connection refused / reset / DNS blips are all EXPECTED right after
+// restart, not a failure signal by themselves. Any HTTP response at all
+// (regardless of status code — a 404 on `/` is normal) proves the process
+// is back up and terminating TLS/HTTP again; that's all "reachable" means
+// here. Resource-level 404s are a separate, later check.
+async function probeReachable(baseUrl, fetchImpl) {
+    try {
+        await fetchImpl(baseUrl, { method: "GET", signal: AbortSignal.timeout(10_000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function pollUntilSettled(baseUrl, timeoutMs, pollIntervalMs, settleStreak, fetchImpl, onProgress) {
+    const deadline = Date.now() + timeoutMs;
+    let streak = 0;
+    let attempt = 0;
+    for (;;) {
+        attempt++;
+        const reachable = await probeReachable(baseUrl, fetchImpl);
+        streak = reachable ? streak + 1 : 0;
+        if (!reachable) {
+            onProgress?.(`waiting for ${baseUrl} to come back up after restart (attempt ${attempt})...`);
+        }
+        if (streak >= settleStreak)
+            return;
+        if (Date.now() >= deadline) {
+            throw new Error(`deploy verification: ${baseUrl} did not settle within ${timeoutMs}ms after restart ` +
+                `(Harper never came back up, or is unusually slow to restart post-deploy)`);
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+async function verifyResourcesServing(baseUrl, resources, fetchImpl) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const notServing = [];
+    for (const name of resources) {
+        const path = `${base}/${name}`;
+        let status;
+        try {
+            const res = await fetchImpl(path, { method: "GET", signal: AbortSignal.timeout(10_000) });
+            status = res.status;
+        }
+        catch (err) {
+            throw new Error(`deploy verification: request to ${path} failed even after the endpoint settled: ${err?.message ?? err}`);
+        }
+        // 404 = the resource genuinely isn't being served (this is the incident:
+        // harper reported "Successfully deployed" while the component was empty).
+        // 401 = auth-gated, which means the resource IS being served correctly.
+        // 200 = served + accessible. Both count as pass.
+        if (status === 404)
+            notServing.push(name);
+    }
+    if (notServing.length) {
+        const list = notServing.map((n) => `/${n}`).join(", ");
+        throw new Error(`deploy reported success but ${list} return${notServing.length === 1 ? "s" : ""} 404 — ` +
+            `component is not serving; likely deployed the wrong package root`);
+    }
+}
+// The tool must not be able to lie. harper's deploy CLI can print
+// "Successfully deployed" for an empty component — the only way to know the
+// deploy actually worked is to curl the served API and check it isn't 404.
+// This polls the served base URL (443, NOT the :9925 ops API deploy talks
+// to) until it settles after harper's post-deploy restart, then asserts the
+// derived resource(s) respond non-404.
+export async function verifyDeployServing(o) {
+    const { baseUrl, resources, timeoutMs = DEFAULT_VERIFY_TIMEOUT_MS, pollIntervalMs = VERIFY_POLL_INTERVAL_MS, settleStreak = VERIFY_SETTLE_STREAK, fetchImpl = fetch, onProgress, } = o;
+    onProgress?.(`verifying ${baseUrl} is actually serving (not just reported deployed)...`);
+    await pollUntilSettled(baseUrl, timeoutMs, pollIntervalMs, settleStreak, fetchImpl, onProgress);
+    onProgress?.(`settled — checking ${resources.map((r) => `/${r}`).join(", ")}...`);
+    await verifyResourcesServing(baseUrl, resources, fetchImpl);
+    onProgress?.(`served API verified non-404 for ${resources.length} resource(s)`);
+}
 export async function deploy(opts) {
     const errors = validateOptions(opts);
     if (errors.length) {
@@ -141,13 +312,7 @@ export async function deploy(opts) {
             "Pass --fabric-user + --fabric-password instead.");
     }
     const harperBin = resolveHarperBin(packageRoot);
-    const args = [
-        "deploy",
-        `target=${url}`,
-        `project=${project}`,
-        `restart=${opts.restart !== false}`,
-        `replicated=${opts.replicated !== false}`,
-    ];
+    const args = buildHarperDeployArgs(opts, url, project);
     // Credentials go via env, not argv, so they don't appear in `ps` output
     // for the lifetime of the Harper child process. Harper's cliOperations
     // reads CLI_TARGET_USERNAME / CLI_TARGET_PASSWORD as env fallbacks.
@@ -157,5 +322,20 @@ export async function deploy(opts) {
         CLI_TARGET_PASSWORD: opts.fabricPassword,
     };
     await spawnHarper(harperBin, args, packageRoot, childEnv);
+    // harper can print "Successfully deployed" for a component that isn't
+    // actually serving anything (the incident this closes: an empty deploy,
+    // reported success, /Memory 404ing in prod). Verify by curling the served
+    // API — on by default, escape hatch via --no-verify.
+    if (opts.verify !== false) {
+        const resources = opts.verifyResources?.length
+            ? opts.verifyResources
+            : deriveVerifyResources(packageRoot);
+        await verifyDeployServing({
+            baseUrl: url,
+            resources,
+            timeoutMs: opts.verifyTimeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS,
+            onProgress: opts.onProgress,
+        });
+    }
     return { url, project, version, packageRoot, dryRun: false };
 }

package/dist/resources/AdminMemory.js

@@ -342,7 +342,7 @@ export class AdminMemory extends Resource {
         <dl style="display:grid;grid-template-columns:200px 1fr;gap:6px;margin-top:8px;font-family:ui-monospace,SF Mono,monospace;font-size:0.85em">
           <dt style="color:#666">id</dt><dd>${esc(m.id)}</dd>
           <dt style="color:#666">contentHash</dt><dd>${esc(m.contentHash ?? "—")}</dd>
-          <dt style="color:#666">visibility</dt><dd>${esc(m.visibility ?? "private")}</dd>
+          <dt style="color:#666">visibility</dt><dd>${esc(m.visibility ?? "shared (no field — pre-migration default)")}</dd>
         </dl>
       </div>
     `;

package/dist/resources/Memory.js

@@ -4,31 +4,23 @@ import { isAdmin, resolveAgentAuth, allowVerified } from "./agent-auth.js";
 import { getEmbedding, getModelId } from "./embeddings-provider.js";
 import { scanFields, isStrictMode } from "./content-safety.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
-import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, isConservativeMatch, } from "./dedup.js";
+import { resolveReadScope } from "./memory-read-scope.js";
+import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
 const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
 /**
- * Owner ids a non-admin agent may READ: itself, plus any owner who has
- * granted it a "read" or "search" scoped MemoryGrant. Shared by search()
- * (collection scoping) and get() (per-id ownership check, memory-soul-read-
- * gate fix) so the two paths cannot drift apart — this was previously
- * computed inline only inside search().
+ * Owner ids a non-admin agent may READ (resolveAllowedOwners) and the full
+ * read-scope condition + private-exclusion predicate (resolveReadScope) now
+ * live in ./memory-read-scope.ts — the ONE centralized helper every
+ * cross-agent Memory read path (search()/get() here, SemanticSearch.ts,
+ * MemoryBootstrap.ts, auth-middleware.ts's by-id guard) resolves its scope
+ * through, so the scoping rule cannot drift per-path again (ops-nzxa: a
+ * SemanticSearch inline `visibility === "office"` OR-clause leaked office
+ * memories to any authenticated agent because the rule had scattered). See
+ * that module's doc for the migration invariant (no-visibility-field reads
+ * as "shared", never "private").
  */
-async function resolveAllowedOwners(authAgentId) {
-    const allowedOwners = [authAgentId];
-    try {
-        for await (const grant of databases.flair.MemoryGrant.search({
-            conditions: [{ attribute: "granteeId", comparator: "equals", value: authAgentId }],
-        })) {
-            if (grant.ownerId && (grant.scope === "read" || grant.scope === "search")) {
-                allowedOwners.push(grant.ownerId);
-            }
-        }
-    }
-    catch { /* MemoryGrant table not yet populated — ignore */ }
-    return allowedOwners;
-}
 /**
  * ─── Server-side conservative-duplicate gate (memory-integrity fix) ──────────
  *
@@ -94,7 +86,59 @@ async function findConservativeDedupMatch(ctx, agentId, contentText, embedding,
         }
         if (!top)
             return null;
-        const cosine = 1 - (top.$distance ?? 1);
+        // ─── ops-ume4: Harper's cosine-sort query omits $distance for a SINGLETON
+        // result set ─────────────────────────────────────────────────────────────
+        // Initial working theory was a per-agentId HNSW "cold-start" (first-ever
+        // query cold, second query warm) and the initially-recommended fix was a
+        // same-query retry. Empirically FALSIFIED: a plain retry of the identical
+        // query, 8x with 300ms delays (2.4s total), never recovered a `$distance`
+        // for a genuinely singleton candidate set (exactly one record matching
+        // `agentId equals X AND archived not_equal true`). The actual trigger,
+        // confirmed by direct probing: when this query's post-filter result set
+        // has exactly ONE matching record, `$distance` comes back `undefined` for
+        // it — regardless of how many prior queries have run for that agentId,
+        // how long you wait, or how many other agentIds/records already exist in
+        // the table. The moment a SECOND matching record exists, `$distance` is
+        // populated correctly on the very first query ever issued for that
+        // agentId — no warm-up needed. In practice the singleton case is exactly
+        // an agent's SECOND-ever memory (compared against their first) — the most
+        // common real-world trigger for this bug, and why it looked "permanent
+        // per-agent for the first near-dup query."
+        //
+        // Also NOT a query-shape/conditions issue: the `{operator:"or"}` wrap
+        // SemanticSearch.ts uses elsewhere is unrelated, and neither raising
+        // `limit` past 1 nor changing the conditions shape changes the result —
+        // confirmed empirically. Harper's SORT ordering is correct even in the
+        // singleton case (the right record comes back as `top`); only the
+        // numeric `$distance` annotation is missing. Also confirmed: selecting
+        // "embedding" directly on THIS sort-by-embedding query does not help
+        // either — it comes back as a bare scalar (Harper appears to special-case
+        // the sort attribute in `select`), not the stored vector.
+        //
+        // Fix: when `$distance` is undefined, fetch the ONE candidate's full
+        // record by id (a plain point lookup — not a vector-sort query, so
+        // unaffected by the quirk above) and compute cosine similarity ourselves
+        // in JS from its real stored `embedding` vector against this write's own
+        // `embedding` (this function's parameter), via the same math Harper would
+        // have used (dedup.ts's cosineSimilarity, Harper-free and unit-tested).
+        // This sidesteps the underlying engine quirk entirely rather than
+        // depending on its timing, and works identically whether this is the
+        // agent's first query ever or its thousandth. Never suppresses the write
+        // either way: if the candidate's embedding is somehow also missing (e.g.
+        // a legacy record written before embeddings existed), `cosineSimilarity`
+        // returns 0 — the same safe "no match" signal the pre-fix `?? 1`
+        // fallback produced.
+        let cosine;
+        if (top.$distance !== undefined) {
+            cosine = 1 - top.$distance;
+        }
+        else {
+            console.error("Memory.findConservativeDedupMatch: $distance undefined on a singleton cosine result (ops-ume4) — " +
+                "falling back to a manual cosine computation from the candidate's stored embedding", { agentId, candidateId: top.id });
+            const fullCandidate = await withDetachedTxn(ctx, () => databases.flair.Memory.get(top.id));
+            const candidateEmbedding = Array.isArray(fullCandidate?.embedding) ? fullCandidate.embedding : [];
+            cosine = cosineSimilarity(embedding, candidateEmbedding);
+        }
         const confidence = computeMatchConfidence(contentText, top.content, cosine);
         if (!isConservativeMatch(confidence.cosine, confidence.lexical, cosineThreshold, lexicalThreshold)) {
             return null;
@@ -252,6 +296,20 @@ async function closeSupersededIfNeeded(ctx, content, methodLabel) {
             "(ops-a4t5 — observable, not silent; new record is safely written, old record remains active until retried)", { method: methodLabel, supersededId: content.supersedes, newRecordId: content.id, err });
     }
 }
+/**
+ * ─── Durability-keyed default visibility (ops-2dm3 Layer 1, part A) ─────────
+ *
+ * Writer intent: an explicit `visibility` on the write ALWAYS overrides this
+ * (callers check `content.visibility == null` before calling this). When
+ * unset, the default is keyed off durability — a durable write (the agent
+ * chose to make this stick around) defaults to shared; anything else
+ * defaults to private. "absent" durability (not yet defaulted by the caller)
+ * falls into the private branch, matching the spec's
+ * "standard|ephemeral|absent → private".
+ */
+function defaultVisibilityForDurability(durability) {
+    return durability === "permanent" || durability === "persistent" ? "shared" : "private";
+}
 export class Memory extends databases.flair.Memory {
     /**
      * Self-authorize now that the global gate is non-rejecting. Closes the P0
@@ -301,14 +359,15 @@ export class Memory extends databases.flair.Memory {
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return super.get(target);
         }
-        // Non-admin agent: only its own memories, or an owner's memories it holds
-        // a read/search MemoryGrant for (same owner-set as search() — shared
-        // resolveAllowedOwners helper so the two paths cannot drift).
+        // Non-admin agent: only its own memories (any visibility), or a granted
+        // owner's SHARED memories — never that owner's private ones (ops-2dm3
+        // Layer 1 private-exclusion). Centralized in resolveReadScope() so this
+        // and search() below cannot drift.
         const record = await super.get(target);
         if (!record)
             return NOT_FOUND();
-        const allowedOwners = await resolveAllowedOwners(auth.agentId);
-        if (!allowedOwners.includes(record.agentId))
+        const scope = await resolveReadScope(auth.agentId);
+        if (!scope.isAllowed(record))
             return NOT_FOUND();
         return record;
     }
@@ -337,13 +396,12 @@ export class Memory extends databases.flair.Memory {
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return super.search(query);
         }
-        // Non-admin agent: scope to own + granted owners.
+        // Non-admin agent: scope to own (any visibility) + granted owners' SHARED
+        // memories only (ops-2dm3 Layer 1 private-exclusion). Centralized in
+        // resolveReadScope() so get() above and search() here cannot drift.
         const authAgent = auth.agentId;
-        const allowedOwners = await resolveAllowedOwners(authAgent);
-        // Build the agentId scope condition
-        const agentIdCondition = allowedOwners.length === 1
-            ? { attribute: "agentId", comparator: "equals", value: allowedOwners[0] }
-            : { conditions: allowedOwners.map(id => ({ attribute: "agentId", comparator: "equals", value: id })), operator: "or" };
+        const scope = await resolveReadScope(authAgent);
+        const agentIdCondition = scope.condition;
         // Harper passes `query` as a RequestTarget (extends URLSearchParams) or a
         // conditions array. For URL-based GET /Memory?... calls, URL params are no
         // longer translated to conditions here — callers should use
@@ -392,6 +450,16 @@ export class Memory extends databases.flair.Memory {
         content.createdAt = new Date().toISOString();
         content.updatedAt = content.createdAt;
         content.archived = content.archived ?? false;
+        // ─── Default visibility (durability-keyed) — ops-2dm3 Layer 1, part A ────
+        // post() only ever creates a NEW record — patchRecord/supersede-close/
+        // retrievalCount bumps all route through put() instead (see put()'s
+        // pre-existing-record guard below), so there is no "don't overwrite an
+        // existing record's visibility" concern here. Explicit visibility on the
+        // write ALWAYS overrides; only stamp the default when the caller left it
+        // unset. permanent|persistent → shared; standard|ephemeral|absent → private.
+        if (content.visibility === undefined || content.visibility === null) {
+            content.visibility = defaultVisibilityForDurability(content.durability);
+        }
         // Validate derivedFrom source IDs exist (best-effort, non-blocking)
         if (Array.isArray(content.derivedFrom) && content.derivedFrom.length > 0) {
             const now = content.createdAt;
@@ -509,6 +577,26 @@ export class Memory extends databases.flair.Memory {
         // Set defaults that post() sets — put() is also used for new records via CLI
         content.archived = content.archived ?? false;
         content.createdAt = content.createdAt ?? now;
+        // Fetch the pre-existing record (if any) ONCE — reused below both to
+        // decide whether this PUT is a fresh create (dedup gate applies, default
+        // visibility stamped) or an update/patch (dedup-bypassed, visibility left
+        // untouched). See the dedup-gate block further down for why an existing
+        // id skips the gate; the SAME "does a record already exist" check gates
+        // the visibility default (ops-2dm3 Layer 1 part A): patchRecord/supersede-
+        // close/retrievalCount bumps all route through put() with a MERGED
+        // `{...existing, ...patch}` payload, and must never have their stored
+        // visibility overwritten by a default recomputed from that merged content
+        // — only a genuinely NEW id gets the default stamped.
+        const preExisting = content.id
+            ? await databases.flair.Memory.get(content.id).catch(() => null)
+            : null;
+        // ─── Default visibility (durability-keyed) — ops-2dm3 Layer 1, part A ────
+        // Explicit visibility on the write ALWAYS overrides; only stamp the
+        // default when the caller left it unset AND this is a fresh record.
+        // permanent|persistent → shared; standard|ephemeral|absent → private.
+        if (!preExisting && (content.visibility === undefined || content.visibility === null)) {
+            content.visibility = defaultVisibilityForDurability(content.durability);
+        }
         // supersedes: optional reference to the ID of the memory this one
         // replaces. Validates shape + cross-agent-write authorization (shared
         // with post() — see validateAndAuthorizeSupersedes doc for why PUT needs
@@ -552,7 +640,6 @@ export class Memory extends databases.flair.Memory {
             delete content.lexicalThreshold;
         }
         else if (content.id) {
-            const preExisting = await databases.flair.Memory.get(content.id).catch(() => null);
             if (!preExisting) {
                 dedupMatch = await runDedupGate(ctx, content);
             }