@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/runtime/uv-bootstrap.mjs

@@ -1,9 +1,19 @@
 /**
  * lib/runtime/uv-bootstrap.mjs — idempotent uv + docling venv provisioner.
  *
- * On first use: downloads uv via the official Astral installer, creates
- * `<rootDir>/.cx/runtime/docling/.venv`, installs the pinned docling release.
- * Subsequent calls are no-ops if the venv is already present.
+ * One venv per machine, not one per project (construct-rf26.16; ADR-0066
+ * called this out as the docling venv's terminal shape). On first use:
+ * downloads uv via the official Astral installer, creates
+ * `~/.construct/runtime/docling/.venv` (or `$CX_TOOLKIT_DIR/runtime/docling/.venv`)
+ * via `resolveSharedRuntimeDir`, installs the pinned docling release.
+ * Subsequent calls from any project on this machine are no-ops once the
+ * venv is present — there is no project key anywhere in this path.
+ *
+ * Version pin is the lockfile: `.install-marker.json`'s `doclingVersion`
+ * field is compared against DOCLING_PIN on every call. A mismatch (a
+ * construct upgrade that bumps the pin) is not silent drift — it clears the
+ * stale venv directory and re-provisions from scratch under `force`
+ * semantics, rather than layering a new install over an old one.
  *
  * Best-practice notes (2026-06):
  *   - uv (Astral) is the consensus Python tooling, ~10× faster than pip, single
@@ -16,19 +26,25 @@
  * Returns the path to the venv's python binary so callers can spawn the
  * sidecar without relying on PATH state.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
 import { spawn, spawnSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
 
+import { resolveSharedRuntimeDir } from '../state-root.mjs';
+
 const DOCLING_PIN = '2.45.0';
 const UV_INSTALL_URL = 'https://astral.sh/uv/install.sh';
 const UV_TIMEOUT_MS = 120_000;
 const VENV_TIMEOUT_MS = 240_000;
 const INSTALL_TIMEOUT_MS = 600_000;
 
-export function defaultRuntimeDir(cwd = process.cwd()) {
-  return path.join(cwd, '.cx', 'runtime', 'docling');
+// ensureDir:false — shared by the provisioner (ensureDoclingVenv, which
+// already mkdirs before it writes) and the read-only detector
+// (describeDoclingRuntime); a detect-only call must not conjure the dir.
+
+export function defaultRuntimeDir() {
+  return resolveSharedRuntimeDir('docling', { ensureDir: false });
 }
 
 function which(bin) {
@@ -127,6 +143,16 @@ export async function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), forc
     return { pythonBin: existingPython, venvDir, runtimeDir, fresh: false };
   }
 
+  // A version-pin mismatch (existingMarker present but doclingVersion !== DOCLING_PIN)
+  // is a controlled re-provision, not silent drift: clear the stale venv outright
+  // rather than trust `uv venv` to reconcile an existing directory left by a
+  // different docling/Python pin.
+
+  if (existingMarker && existingMarker.doclingVersion !== DOCLING_PIN) {
+    progress(`Pinned docling version changed (${existingMarker.doclingVersion} → ${DOCLING_PIN}) — re-provisioning.`);
+    try { rmSync(venvDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+
   progress('Provisioning the docling document extractor (first run). This downloads a Python runtime and ML dependencies and can take several minutes; later runs are instant.');
   const uv = await ensureUv(runtimeDir);
 

package/lib/runtime/whisper-bootstrap.mjs

@@ -12,8 +12,9 @@
  *
  * Model files are downloaded directly from Hugging Face the first time the
  * default `base.en` (or env-overridden) model is requested. Models cache at
- * <runtimeDir>/models/. base.en is ~150MB; smaller than the small.en or
- * medium.en model that callers can opt into via CONSTRUCT_WHISPER_MODEL.
+ * <stateRoot>/runtime/whisper/models/ (ADR-0066: machine-scoped, not
+ * project-local). base.en is ~150MB; smaller than the small.en or medium.en
+ * model that callers can opt into via CONSTRUCT_WHISPER_MODEL.
  *
  * No bundled distribution: whisper.cpp upstream does not publish stable
  * pre-built CLI binaries across platforms, and building from source via
@@ -25,12 +26,19 @@ import { pipeline } from 'node:stream/promises';
 import path from 'node:path';
 import os from 'node:os';
 
+import { resolveStateDir } from '../state-root.mjs';
+
 const HF_MODEL_BASE_URL = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main';
 const DEFAULT_MODEL = process.env.CONSTRUCT_WHISPER_MODEL || 'base.en';
 const KNOWN_MODELS = new Set(['tiny', 'tiny.en', 'base', 'base.en', 'small', 'small.en', 'medium', 'medium.en', 'large-v3', 'large-v3-turbo']);
 
+// ensureDir:false — shared by the provisioner (ensureWhisperRuntime, which
+// already mkdirs before it writes) and the read-only detector
+// (describeWhisperRuntime/locateWhisperBinary); a detect-only call must not
+// conjure the dir.
+
 export function defaultRuntimeDir(cwd = process.cwd()) {
-  return path.join(cwd, '.cx', 'runtime', 'whisper');
+  return resolveStateDir(cwd, 'runtime', 'whisper', { ensureDir: false });
 }
 
 function which(bin) {

package/lib/runtime-env.mjs

@@ -1,8 +1,11 @@
 /**
  * lib/runtime-env.mjs — Construct runtime environment with credential bootstrap.
  *
- * prepareConstructEnv merges ~/.config/construct/config.env into the process environment.
- * Credential auto-link from 1Password runs only when autoLink:true (setup-credentials).
+ * prepareConstructEnv merges the user's ~/.config/construct/config.env and,
+ * when the caller passes `rootDir` (the resolved project root, not the
+ * toolkit install checkout), the project .env into the process environment —
+ * project .env wins. Credential auto-link from 1Password runs only when
+ * autoLink:true (setup-credentials).
  */
 
 import { loadConstructEnv } from './env-config.mjs';

package/lib/sandbox.mjs

@@ -55,7 +55,7 @@ export function createSandbox({ profile = null, seedContext = null } = {}) {
   fs.writeFileSync(path.join(root, '.cx', 'context.md'), ctx);
 
   const cfg = { version: 1, alias: 'Construct', deployment: { mode: 'solo' } };
-  if (profile) cfg.profile = profile;
+  if (profile) cfg.scope = profile;
   fs.writeFileSync(path.join(root, 'construct.config.json'), JSON.stringify(cfg, null, 2) + '\n');
 
   spawnSync('git', ['init', '--quiet'], { cwd: root, stdio: 'ignore' });

package/lib/scheduler/index.mjs

@@ -8,11 +8,15 @@
  *
  * Jobs registered here: 'tag-candidate-mining', 'skill-usage-rollup', 'doc-hygiene-scan'
  *
- * Deployment mode is determined by getDeploymentMode(env), which inspects env vars.
+ * Deployment mode is resolved through the canonical lib/deployment-mode.mjs
+ * getDeploymentMode (CONSTRUCT_DEPLOYMENT_MODE env, then project config, then solo),
+ * so the scheduler agrees with the broker, session prelude, and status surfaces.
  * Registration is in-memory: no persistence across process restarts beyond the
  * native trigger files written by solo.mjs or the DB rows in 009_scheduler.sql.
  */
 
+import { getDeploymentMode } from '../deployment-mode.mjs';
+
 // ---------------------------------------------------------------------------
 // In-memory job registry
 // ---------------------------------------------------------------------------
@@ -57,22 +61,6 @@ export function listJobs() {
   }));
 }
 
-/**
- * Derives the deployment mode from environment variables.
- * Returns 'enterprise' | 'team' | 'solo'.
- *
- * CONSTRUCT_DEPLOYMENT=enterprise or CONSTRUCT_ENTERPRISE=1 => enterprise
- * CONSTRUCT_DEPLOYMENT=team or CONSTRUCT_TEAM=1             => team
- * Otherwise                                                  => solo
- */
-export function getDeploymentMode(env = process.env) {
-  const explicit = env.CONSTRUCT_DEPLOYMENT;
-  if (explicit === 'enterprise' || env.CONSTRUCT_ENTERPRISE === '1') return 'enterprise';
-  if (explicit === 'team' || env.CONSTRUCT_TEAM === '1') return 'team';
-  if (explicit === 'solo') return 'solo';
-  return 'solo';
-}
-
 // ---------------------------------------------------------------------------
 // Built-in job registrations
 // ---------------------------------------------------------------------------
@@ -104,8 +92,8 @@ registerJob({
 const DOC_HYGIENE_SOLO_CRON = '0 2 * * *';
 const DOC_HYGIENE_TEAM_CRON = '0 * * * *';
 
-export function resolveDocHygieneSchedule(env = process.env) {
-  const mode = getDeploymentMode(env);
+export function resolveDocHygieneSchedule(env = process.env, { cwd } = {}) {
+  const mode = getDeploymentMode(env, { cwd });
   const isTeamish = mode === 'team' || mode === 'enterprise';
   return {
     mode: isTeamish ? 'team' : 'solo',
@@ -121,7 +109,7 @@ registerJob({
   mode: docHygiene.mode,
   handler: async ({ cwd, env }) => {
     const { findHygieneCandidates } = await import('../hygiene/scan.mjs');
-    const { limit } = resolveDocHygieneSchedule(env);
+    const { limit } = resolveDocHygieneSchedule(env, { cwd });
     const candidates = findHygieneCandidates({ cwd, limit });
     return {
       status: 'ok',

package/lib/schema-infer.mjs

@@ -25,6 +25,7 @@ import { extractDocumentTextNodeNative, extractDocumentTextAsync } from './docum
 import { readCurrentModels, readOpenRouterApiKeyFromOpenCodeConfig } from './model-router.mjs';
 import { getUserEnvPath } from './env-config.mjs';
 import { pollFreeModels, topForTier } from './model-free-selector.mjs';
+import { extractOpRef, resolveOpRef, resolveSecret } from './providers/secret-resolver.mjs';
 import { execSync } from 'node:child_process';
 
 // ---------------------------------------------------------------------------
@@ -187,9 +188,37 @@ async function fetchWithTimeout(url, options) {
   }
 }
 
+function resolveSecretOrNull(varName, { env = process.env, allowAmbient = true } = {}) {
+  try {
+    return resolveSecret(varName, { env, allowAmbient });
+  } catch {
+    return null;
+  }
+}
+
+function materializeConfiguredKey(rawValue) {
+  if (typeof rawValue !== 'string' || rawValue.length === 0) return null;
+  const ref = extractOpRef(rawValue);
+  try {
+    return ref ? resolveOpRef(ref) : rawValue;
+  } catch {
+    return null;
+  }
+}
+
+function resolveOpenRouterApiKey() {
+  const envKey = resolveSecretOrNull('OPENROUTER_API_KEY');
+  if (envKey) return envKey;
+  try {
+    return materializeConfiguredKey(readOpenRouterApiKeyFromOpenCodeConfig());
+  } catch {
+    return null;
+  }
+}
+
 async function callModel(userContent, { traceId } = {}) {
-  const orKey = process.env.OPENROUTER_API_KEY || readOpenRouterApiKeyFromOpenCodeConfig();
-  const anthropicKey = process.env.ANTHROPIC_API_KEY;
+  const orKey = resolveOpenRouterApiKey();
+  const anthropicKey = resolveSecretOrNull('ANTHROPIC_API_KEY');
 
   if (!orKey && !anthropicKey) {
     throw new Error('No API key found. Set ANTHROPIC_API_KEY or OPENROUTER_API_KEY to use schema inference.');

package/lib/scopes/lifecycle.mjs

@@ -10,7 +10,11 @@
  *
  * Lifecycle stages:
  *   draft     - in `.cx/scopes/draft-<id>/` with requirements.md + scope.json
- *   active    - in `specialists/org/scopes/<id>.json` (curated) or `.cx/scope.json` (custom)
+ *   active    - in `specialists/org/scopes/<id>.json` (curated), or a named
+ *               custom profile under the construct-rf26.13 config-layer tiers
+ *               (`~/.construct/org/scopes/<id>.json` or
+ *               `<project>/.cx/org/scopes/<id>.json`), or the single-file
+ *               `.cx/scope.json` escape hatch (custom, anonymous)
  *   archived  - in `archive/scopes/<id>/` with the final state and an
  *               archive-note.md explaining why it was retired
  *
@@ -41,23 +45,22 @@ function archiveDir(cwd, id) {
 
 const REQUIREMENTS_BRIEF = (id, displayName) => `# Scope requirements: ${displayName} (${id})
 
-This brief is a discovery and design contract for a new Construct scope. Methodology lives in \`docs/guides/concepts/persona-research.md\` and lifecycle in \`docs/guides/concepts/scope-lifecycle.md\`. Treat each section as a task to dispatch to the named specialist. A draft scope is not ready to promote until every section has evidence backing it. The aim is research-grounded, not opinion-grounded.
+This brief is a discovery and design contract for a new Construct scope. Methodology lives in \`docs/guides/concepts/persona-research.md\` and lifecycle in \`docs/guides/concepts/profile-lifecycle.md\`. Treat each section as a task to dispatch to the named specialist. A draft scope is not ready to promote until every section has evidence backing it. The aim is research-grounded, not opinion-grounded.
 
 Specialists used here are the existing Construct cx-* personas (already in the registry). They are dispatched the standard way; this doc just names which questions each one owns.
 
+A scope selects flows and skill emphasis over the shared, fixed 12-role core roster (\`specialists/org/specialists/\`) — it does not invent new roles or departments. If this org genuinely needs a role absent from that roster, author it as a custom specialist via the construct-rf26.13 config layer (\`construct specialist create <id> --custom\`, docs/guides/cookbook/custom-specialists-and-teams.md) rather than declaring it inline here.
+
 This draft scaffolding produces:
-- \`scope.json\` — the structural definition (departments, roles, intake)
+- \`scope.json\` — the structural definition (intake taxonomy, doc templates, skill emphasis)
 - \`requirements.md\` — this brief
-- \`personas/<role>.md\` — one persona artifact per role (filled during the discover phase)
-- \`departments/<dept>.md\` — one charter doc per department (filled during the frame phase)
-
-The persona and department files start as templates. Filling them from evidence is the actual work; the JSON is just a manifest.
+- \`personas/<role>.md\` — optional, only when \`seedRoles\` names a role genuinely absent from the core roster (rare; most orgs route entirely through the existing 12)
 
-## 1. Discovery (cx-ux-researcher)
+## 1. Discovery (cx-researcher)
 
 Goal: characterize the people, the work, and the outputs of this org type.
 
-- Who are the typical roles in this org? Name 4 to 8 with one-line responsibilities.
+- Which of the 12 core roles (architect, reviewer, engineer, debugger, qa, security, operations, product-manager, data-analyst, designer, researcher, orchestrator) are primary for this org, and which are rarely if ever needed?
 - What is the dominant work loop? Describe in 5 to 8 stages.
 - What are the recurring signals that enter the loop (briefs, bug reports, customer messages, etc.)?
 - What are the canonical output artifacts (campaigns, runbooks, papers, etc.)?
@@ -67,23 +70,23 @@ Goal: characterize the people, the work, and the outputs of this org type.
 
 Goal: turn discovery into an intake taxonomy and a stage sequence.
 
-- Propose intake types (max 24). Each must be: distinct, observable, and routable to a primary owner.
+- Propose intake types (max 24). Each must be: distinct, observable, and routable to a primary owner among the 12 core roles.
 - Propose stages (max 12). Order matters; each stage must answer "what changed?" not just "what happened next?".
-- For each intake type, name the primary owner role and the recommended chain (max 3 hops).
+- For each intake type, name the primary owner role (one of the 12) and the recommended chain (max 3 hops).
 - For each stage, name the dominant artifact produced.
 - Acceptance: a representative real signal classifies into a single intake type with confidence > 0.6.
 
-## 3. Architecture (cx-architect)
+## 3. Skill emphasis (cx-architect)
 
-Goal: define the role set and how it interlocks with the curated cx-* registry.
+Goal: pick the flows and skill bundles this profile should emphasize from the shared registry — not a new role set.
 
-- List role ids the scope will reference (max 80, grouped into max 12 departments with max 20 roles per department). For each, indicate one of:
-  reuse-existing (name the cx-* agent), create-new (specify scope), or compose-overlay (which base role + which flavor).
-- Identify cross-role handoffs. Where can ambiguity stall the loop? Name the orchestrator role.
-- Validate against the per-role cap (max 6 flavors per role per scope).
-- Acceptance: every declared role either exists in specialists/org or has a written scope statement.
+- For each doc template the profile ships, confirm a docTemplates entry exists and name its owning role.
+- List the \`defaultSkills\` (skill ids under \`skills/\`) this org's work loop leans on most — these become the profile's baseline skill entitlement (lib/skills/router.mjs), on top of whatever an individual specialist already carries.
+- Set \`researchProfiles\` per intake type (external, user, codebase, market, compliance) and \`toneDefaults\` per doc template.
+- Name the orchestrator's role in this loop (routing/dispatch is always cx-orchestrator; this just confirms nothing here bypasses it).
+- Acceptance: every \`defaultSkills\` entry resolves to a real file under \`skills/\`; every doc template maps to an owning role among the 12.
 
-## 4. Validation (cx-evaluator)
+## 4. Validation (cx-reviewer)
 
 Goal: prove the draft works on real signals before promotion.
 
@@ -93,13 +96,14 @@ Goal: prove the draft works on real signals before promotion.
 
 ## 5. Promotion (operator decision)
 
-Goal: move the draft into the active catalog.
+Goal: move the draft into the active catalog, or leave it as a durable custom profile.
 
 - Curated path: hand-edit \`specialists/org/scopes/${id}.json\` from this draft, open a PR, run \`npm run lint:scopes\`.
-- Custom path: copy the draft scope.json to \`<project>/.cx/scope.json\` with \`"custom": true\`; \`construct scope set\` for switching between curated.
-- Either path requires the validation acceptance criteria above to be met.
+- Custom path (named, reusable): copy the draft scope.json to \`<project>/.cx/org/scopes/${id}.json\` (project tier, git-tracked) or \`~/.construct/org/scopes/${id}.json\` (user tier, shared across projects) — the same builtin -> user -> project precedence construct-rf26.13 gives custom specialists and teams. Then \`construct scope set ${id}\` switches to it exactly like a curated scope.
+- Custom path (anonymous, one-off): copy the draft scope.json to \`<project>/.cx/scope.json\` with \`"custom": true\` — the pre-rf26.13 escape hatch, still supported for a single ad hoc override.
+- Any path requires the validation acceptance criteria above to be met.
 
-## 6. Health monitoring (cx-evaluator + cx-trace-reviewer)
+## 6. Health monitoring (cx-reviewer)
 
 Goal: keep the scope honest after it ships.
 
@@ -107,7 +111,7 @@ Goal: keep the scope honest after it ships.
 - Any role with success-rate < 0.5 across 10+ runs triggers a review: is the role wrong, the prompt wrong, or the routing wrong?
 - Health data is the input for future scope revisions; never edit a scope without a health report first.
 
-## 7. Archive (cx-docs-keeper + operator)
+## 7. Archive (cx-operations + operator)
 
 Goal: retire a scope cleanly without losing the learning.
 
@@ -397,7 +401,7 @@ export function scopeHealth(cwd, scopeId, { windowDays = 30 } = {}) {
 
   return {
     scope: scopeId,
-    scopeExists: !!loadScope(scopeId),
+    scopeExists: !!loadScope(scopeId, { cwd }),
     windowDays,
     observationCount,
     roles: roleSummary,

package/lib/scopes/loader.mjs

@@ -1,12 +1,23 @@
 /**
  * lib/scopes/loader.mjs — Work-scope loader (intake lens + org enrichment).
  *
- * Curated scopes live in specialists/org/scopes/<id>.json. Custom overrides
- * use <cwd>/.cx/scope.json with custom: true. construct.config.json scope
- * field selects the active scope id (default rnd).
+ * Curated scopes live in specialists/org/scopes/<id>.json. Named custom
+ * scopes reuse the builtin -> user -> project precedence construct-rf26.13
+ * established for specialists/teams (lib/registry/assemble.mjs): an id also
+ * resolves from ~/.construct/org/scopes/<id>.json (shared across every
+ * project on the machine) and <cwd>/.cx/org/scopes/<id>.json (git-tracked,
+ * highest precedence), instead of a scope-specific mechanism. A later tier's
+ * fields shallow-merge over an earlier tier's on id collision.
  *
- * Teams and roles are not authored in scope files — enrich.mjs attaches them
- * from specialists/org at load time.
+ * The single-file <cwd>/.cx/scope.json escape hatch (custom: true) still
+ * works for an anonymous, one-off override — it predates rf26.13 and stays
+ * for the "just this project, no id to remember" case — but a named, reusable
+ * custom profile should live under the tiered org/scopes/ layer so it can be
+ * switched to with `construct scope set <id>` like a curated one.
+ *
+ * construct.config.json's scope field selects the active curated/custom id
+ * (default rnd). Teams and roles are not authored in scope files — enrich.mjs
+ * attaches them from specialists/org at load time.
  */
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
@@ -14,6 +25,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { enrichScope } from './enrich.mjs';
+import { homeDir } from '../paths.mjs';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(MODULE_DIR, '..', '..');
@@ -21,18 +33,43 @@ const SCOPES_DIR = join(REPO_ROOT, 'specialists', 'org', 'scopes');
 
 export const DEFAULT_SCOPE_ID = 'rnd';
 
-export function loadScope(id, opts = {}) {
-  if (!id || typeof id !== 'string') return null;
-  const path = join(SCOPES_DIR, `${id}.json`);
-  if (!existsSync(path)) return null;
+function userScopesDir() {
+  return join(homeDir(), '.construct', 'org', 'scopes');
+}
+
+function projectScopesDir(cwd) {
+  return join(cwd, '.cx', 'org', 'scopes');
+}
+
+function readScopeTier(dir, id) {
+  const p = join(dir, `${id}.json`);
+  if (!existsSync(p)) return null;
   try {
-    const raw = JSON.parse(readFileSync(path, 'utf8'));
-    return enrichScope(raw, opts);
+    return JSON.parse(readFileSync(p, 'utf8'));
   } catch {
     return null;
   }
 }
 
+function resolveScopeRaw(id, cwd) {
+  const tiers = [SCOPES_DIR, userScopesDir(), projectScopesDir(cwd)];
+  let merged = null;
+  for (const dir of tiers) {
+    const raw = readScopeTier(dir, id);
+    if (!raw) continue;
+    merged = merged ? { ...merged, ...raw } : raw;
+  }
+  return merged;
+}
+
+export function loadScope(id, opts = {}) {
+  if (!id || typeof id !== 'string') return null;
+  const cwd = opts.cwd || process.cwd();
+  const raw = resolveScopeRaw(id, cwd);
+  if (!raw) return null;
+  return enrichScope(raw, opts);
+}
+
 export function listScopes() {
   if (!existsSync(SCOPES_DIR)) return [];
   return readdirSync(SCOPES_DIR)
@@ -64,7 +101,7 @@ export function loadCustomScope(cwd) {
 
 export function resolveActiveScope(cwd, configScopeId = null) {
   const rootDir = REPO_ROOT;
-  const enrichOpts = { rootDir };
+  const enrichOpts = { rootDir, cwd };
   if (configScopeId) {
     const s = loadScope(configScopeId, enrichOpts);
     if (s) return s;

package/lib/scopes/teams.mjs

@@ -10,7 +10,7 @@ const OPERATIONS_OBJECTIVE_RULES = [
   {
     teamId: 'operations-team',
     focus: 'reliability',
-    attachTo: ['cx-sre', 'cx-docs-keeper'],
+    attachTo: ['cx-operations'],
     pattern: /\b(incident|outage|deploy|deployment|rollback|reliability|runbook|postmortem|sre|on-?call)\b/i,
   },
   {

package/lib/security/ingest-boundary.mjs

@@ -0,0 +1,80 @@
+/**
+ * lib/security/ingest-boundary.mjs — Source-kind → trust-level mapping at the
+ * ingest boundary.
+ *
+ * Maps named source kinds (provider type, pipeline stage, ingestion method)
+ * to canonical trust levels and stamps them onto records using the primitives
+ * in lib/security/trust.mjs.
+ *
+ * The module is additive — existing ingest, embed, or storage code is not modified.
+ * Callers that want labeling import `stampIngestBoundary` and
+ * apply it at the point where external content enters Construct's data layer.
+ *
+ * References: CX-AUDIT-LLMSEC-001, construct-9oi4.14.1
+ */
+
+import { TRUST_LEVELS, stampTrust } from './trust.mjs';
+
+// ---------------------------------------------------------------------------
+// Source-kind registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Mapping from well-known source kind strings to trust levels.
+ * All entries are lowercase; callers should normalise before lookup.
+ */
+const SOURCE_KIND_MAP = {
+  // Built-in / internal
+  'builtin-prompt':   TRUST_LEVELS.TRUSTED_INTERNAL,
+  'validated-pack':   TRUST_LEVELS.TRUSTED_INTERNAL,
+
+  // Team-authored local content
+  'team-authored':    TRUST_LEVELS.TEAM_AUTHORED,
+  'local-committed':  TRUST_LEVELS.TEAM_AUTHORED,
+
+  // Authenticated external providers
+  'github-issue':     TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'github-pr':        TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'github-comment':   TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'jira-ticket':      TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'jira-comment':     TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'confluence-page':  TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'linear-issue':     TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+
+  // Unauthenticated / parsed / scraped content
+  'docling-parsed':   TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  'web-fetched':      TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  'web-search-result': TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  'pdf-extracted':    TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  'unknown':          TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+};
+
+/**
+ * Resolve the trust level for a given source kind string.
+ * Unrecognised kinds default to EXTERNAL_UNAUTHENTICATED (fail-safe).
+ *
+ * @param {string} sourceKind
+ * @returns {string} TRUST_LEVELS value
+ */
+export function resolveTrustLevel(sourceKind) {
+  const key = (sourceKind ?? 'unknown').toLowerCase();
+  return SOURCE_KIND_MAP[key] ?? TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED;
+}
+
+/**
+ * Stamp a trust label onto a record at the ingest boundary.
+ *
+ * Maps `sourceKind` to the appropriate trust level and delegates to
+ * `stampTrust`. The resulting record has a `_trust` field that downstream
+ * consumers (recall wrappers, context assemblers) can inspect.
+ *
+ * @param {Record<string, unknown>} record     The record being ingested.
+ * @param {string}                  sourceKind Well-known source kind string.
+ * @param {{ sourceRef?: string }}  [options]  Optional extra metadata.
+ * @returns {Record<string, unknown>} Stamped record (source record not mutated).
+ */
+export function stampIngestBoundary(record, sourceKind, options = {}) {
+  const level = resolveTrustLevel(sourceKind);
+  const source = options.sourceRef ?? sourceKind ?? 'unknown';
+  return stampTrust(record, level, source);
+}

package/lib/security/recall-wrapper.mjs

@@ -0,0 +1,99 @@
+/**
+ * lib/security/recall-wrapper.mjs — Trust-aware context assembly for recalled
+ * records.
+ *
+ * Before a set of recalled observations or documents is assembled into model
+ * context, callers pass them through `wrapForContextAssembly`. Records
+ * stamped as external (authenticated or unauthenticated) are wrapped with
+ * explicit untrusted delimiters. Internal and team-authored records pass
+ * through unchanged. Unstamped records are warned and treated as the most
+ * restrictive level: EXTERNAL_UNAUTHENTICATED.
+ *
+ * The module is additive — existing memory, recall, or context assembly code is not modified.
+ * Integration is left to follow-on beads (N2, N4).
+ *
+ * References: CX-AUDIT-LLMSEC-001, construct-9oi4.14.1
+ */
+
+import { TRUST_LEVELS, recallTrustGrade, stampTrust, wrapUntrusted } from './trust.mjs';
+
+// Trust levels that require the untrusted-delimiter treatment.
+const UNTRUSTED_LEVELS = new Set([
+  TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+]);
+
+/**
+ * Wrap a single recalled record for safe context assembly.
+ *
+ * - TRUSTED_INTERNAL / TEAM_AUTHORED → returned as-is.
+ * - EXTERNAL_AUTHENTICATED / EXTERNAL_UNAUTHENTICATED → content wrapped with
+ *   `[UNTRUSTED:…]` delimiters in both the `content` field (if present) and
+ *   as a `_wrappedContent` convenience field.
+ * - No `_trust` stamp → warned, treated as EXTERNAL_UNAUTHENTICATED.
+ *
+ * @param {Record<string, unknown>} record  A recalled observation/document.
+ * @param {{ warn?: (msg: string) => void }} [opts]
+ * @returns {Record<string, unknown>} Wrapped or passthrough record.
+ */
+export function wrapRecordForContext(record, opts = {}) {
+  const warn = opts.warn ?? ((msg) => console.warn('[recall-wrapper]', msg));
+  let trustMeta = recallTrustGrade(record);
+
+  if (trustMeta === null) {
+    warn(
+      `Recalled record has no _trust stamp — treating as ${TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED}. ` +
+      `Record keys: ${Object.keys(record ?? {}).join(', ') || '(empty)'}`,
+    );
+    // Re-stamp defensively so downstream consumers always see _trust.
+    const stamped = stampTrust(
+      record,
+      TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+      'unstamped-recall',
+    );
+    trustMeta = stamped._trust;
+    record = stamped;
+  }
+
+  if (!UNTRUSTED_LEVELS.has(trustMeta.level)) {
+    // TRUSTED_INTERNAL or TEAM_AUTHORED — pass through unchanged.
+    return record;
+  }
+
+  // External content: wrap any present content field and attach _wrappedContent.
+  const rawContent = record.content ?? record.text ?? record.body ?? null;
+  const wrapped = rawContent != null
+    ? wrapUntrusted(String(rawContent), trustMeta)
+    : null;
+
+  return {
+    ...record,
+    ...(wrapped != null ? { _wrappedContent: wrapped } : {}),
+  };
+}
+
+/**
+ * Wrap an array of recalled records for safe context assembly.
+ *
+ * Iterates each record through `wrapRecordForContext`. The returned array
+ * preserves original order. Non-object entries are returned as-is with a
+ * warning (defensive).
+ *
+ * @param {unknown[]} records  Array of recalled observations or documents.
+ * @param {{ warn?: (msg: string) => void }} [opts]
+ * @returns {unknown[]} Array of wrapped/passthrough records.
+ */
+export function wrapForContextAssembly(records, opts = {}) {
+  if (!Array.isArray(records)) {
+    throw new TypeError('wrapForContextAssembly: records must be an array');
+  }
+  const warn = opts.warn ?? ((msg) => console.warn('[recall-wrapper]', msg));
+
+  return records.map((record, idx) => {
+    if (record === null || typeof record !== 'object') {
+      warn(`Record at index ${idx} is not an object — skipping wrap (type: ${typeof record})`);
+      return record;
+    }
+    return wrapRecordForContext(record, { warn });
+  });
+}