@pareto4/pp-core 1.9.0 → 1.11.0

package/pp-core/bin/lib/org-profile.cjs

@@ -0,0 +1,696 @@
+"use strict";
+/**
+ * src/org-profile.cts — the org profile resolver (milestone v1.11.0, Phase 33-01).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/org-profile.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is locked by
+ * `tests/org-profile.test.cjs`.
+ *
+ * This module resolves an OPTIONAL, operator-named npm package — the "org
+ * profile" — that carries a small set of vault/platform coordinates for a
+ * single operator's projects. The package name lives entirely in the
+ * consuming project's own `.planning/config.json`; pp-core's own source
+ * never names one (ORG-01, SC1). An install that configures no such
+ * pointer resolves nothing, warns about nothing, and probes no filesystem
+ * beyond the one config read every project already pays for (ORG-02).
+ *
+ * It imports ONLY node builtins (`node:fs`, `node:path`) at the top level —
+ * no `./vault.cjs`, `./vault-coordinates.cjs`, `./vault-write-back.cjs`,
+ * `./io.cjs`, `./shell-command-projection.cjs`. This is load-bearing: in
+ * 33-03 BOTH `src/git-provider.cts` and `src/vault-coordinates.cts` import
+ * THIS module at their own top level. If this module imported either of
+ * them back, that pair would form a load-time require cycle in the
+ * CommonJS graph that `require` loads — the exact hazard the cycle-avoidance
+ * comments at `src/git-provider.cts:9-23` and
+ * `src/vault-coordinates.cts:22-28` exist to prevent, and the reason both
+ * of those files write their own inline `cfgGet` instead of importing one
+ * from each other.
+ *
+ * The one exception is a CALL-TIME lazy `require('./git-provider.cjs')`
+ * inside `profileValueDisposition`, executed only when a profile value is
+ * actually being validated, never at module load. This is the same
+ * lazy-require seam `src/vault-command-router.cts` already uses for
+ * `./vault.cjs` and `./vault-write-back.cjs`, and it is safe here precisely
+ * because `git-provider.cjs` has no top-level dependency on this module —
+ * by the time any value is being validated, that module is either already
+ * in the require cache or loads cleanly on its own. D-10 requires reusing
+ * the shared shape predicates (`normalizeProvider`, `PROVIDERS`) rather
+ * than writing a second regex; the lazy seam is how a zero-import leaf can
+ * still do that.
+ *
+ * This file's own prose and code deliberately never name a concrete org
+ * profile package or any client — the pointer is described only as "the
+ * npm package name an operator configures". `tests/org-profile.test.cjs`
+ * proves this with an automated scan (SC1).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOST_FORBIDDEN_CHARS = exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS = exports.ORG_PROFILE_SEED_KEYS = exports.ORG_PROFILE_SEED_SECTION = exports.ORG_PROFILE_ALLOWLIST = exports.ORG_PROFILE_DATA_FILE = exports.ORG_PROFILE_CONFIG_KEY = void 0;
+exports.resolveOrgProfileDocument = resolveOrgProfileDocument;
+exports.resolveOrgProfile = resolveOrgProfile;
+exports.readProfileValue = readProfileValue;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** The dotted `.planning/config.json` key naming the profile package. Deliberately
+ * top-level, NOT nested under `vault.`, because the profile also supplies
+ * `platform.host` (D-02). */
+exports.ORG_PROFILE_CONFIG_KEY = 'org.profile';
+/** The fixed filename read from the resolved package's own directory — never the
+ * package's `main`/`exports` entry, and never loaded via `require` (D-08). */
+exports.ORG_PROFILE_DATA_FILE = 'org-profile.json';
+/**
+ * D-06's fixed allowlist: a profile may contribute exactly these five dotted
+ * config keys. Entry order is not contractual; membership is. Anything else
+ * present in a profile document is dropped with a bounded warning.
+ */
+exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
+    'vault.provider',
+    'vault.fallback_repo',
+    'vault.fallback_ref',
+    'vault.fallback_host',
+    'platform.host',
+]);
+/**
+ * The single top-level key naming the Phase 34 init-only seed section.
+ *
+ * This namespace is read ONLY by the Phase 34 bindings composer
+ * (`pp-tools query compose-bindings`, invoked by `/pp-init`) — never by
+ * `resolveOrgProfile`, `readProfileValue`, or any of their consumers
+ * (`resolveProvider`, `resolvePlatformHost`, `resolveSharedCoordinates`). It
+ * is deliberately ABSENT from `ORG_PROFILE_ALLOWLIST` (D-01): extending the
+ * runtime allowlist to cover it would reopen Phase 33 D-05's threat —
+ * `assertVaultWriteTarget` decides by the resolved `(repo, host)` pair, so a
+ * key that layers at RUNTIME is a key an `npm update` can silently move
+ * under the write guard. A seed value only ever reaches the guard via a
+ * file a human ran `/pp-init` to produce, reviewed, and committed — never
+ * directly from the package.
+ */
+exports.ORG_PROFILE_SEED_SECTION = 'bindings';
+/**
+ * The five dotted leaf keys the seed section may carry, each prefixed with
+ * `ORG_PROFILE_SEED_SECTION`. Membership is contractual; entry ORDER is not.
+ *
+ * This array is a DESCRIPTION of the section's shape, not a validator —
+ * value guards (required-vs-optional, host/clone-target forms) live in the
+ * Phase 34 bindings composer, not here.
+ */
+exports.ORG_PROFILE_SEED_KEYS = Object.freeze([
+    `${exports.ORG_PROFILE_SEED_SECTION}.platform.repo`,
+    `${exports.ORG_PROFILE_SEED_SECTION}.client.vaultRepo`,
+    `${exports.ORG_PROFILE_SEED_SECTION}.client.vaultRef`,
+    `${exports.ORG_PROFILE_SEED_SECTION}.client.vaultHost`,
+    `${exports.ORG_PROFILE_SEED_SECTION}.provisioning.group`,
+]);
+/**
+ * D-10's four machine-specific clone-target forms, copied VERBATIM (not
+ * re-authored) from `LITERAL_CLONE_TARGET_PATTERNS` in `src/git-provider.cts`
+ * — the explicit-relative, parent-relative, home-relative and Windows
+ * drive-path forms. These are valid-but-warned when an operator types them
+ * (Phase 32 D-04) but REJECTED outright when a profile package supplies
+ * them, because a human chose one deliberately and a package did not.
+ * `tests/org-profile.test.cjs` pins that every entry here is `===`-identical
+ * to a member of the upstream array, so an upstream edit goes red here
+ * instead of silently desyncing. The absolute-unix-path form, the
+ * scheme-URL form and the scp-style form are deliberately NOT among these
+ * four — D-10 names exactly four machine-specific forms, and everything
+ * else `isLiteralCloneTarget` accepts stays accepted from a profile.
+ */
+exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS = Object.freeze([
+    '^\\.\\/', // explicit relative — ./path
+    '^\\.\\.\\/', // parent-relative — ../path
+    '^~', // home-relative — ~ or ~/path
+    '^[A-Za-z]:[\\\\/]', // Windows drive path — C:\ or C:/
+]);
+// Compiled once at module load, without the global flag (a global regex
+// carries `lastIndex` state across `test` calls and would make the
+// predicate answer differently on repeated identical inputs) — the same
+// convention `src/git-provider.cts` uses for `LITERAL_CLONE_TARGET_PATTERNS`.
+const compiledRejectedCloneTargetPatterns = exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS.map((source) => new RegExp(source));
+/**
+ * Characters a profile-supplied host may never contain (T-33-04).
+ *
+ * `vault.fallback_host` and `platform.host` are interpolated by
+ * `composeCloneTarget` as the AUTHORITY of `https://{host}/{repo}`, so this
+ * guard has to do more than keep a path out of the value — it has to keep
+ * the value from escaping the authority component at all.
+ *
+ * `@` is the load-bearing entry: `dev.azure.com@attacker.example.com`
+ * composes to `https://dev.azure.com@attacker.example.com/…`, which every
+ * RFC-3986 parser reads as userinfo `dev.azure.com` at host
+ * `attacker.example.com`. Since a profile is dependency-supplied, that is a
+ * silent `npm update`-reachable redirect of the clone — and of the
+ * `(repo, host)` pair `assertVaultWriteTarget` decides on. `?` and `#`
+ * terminate the authority early. `/` and `\` carry a path.
+ *
+ * `:` is deliberately absent — a port is legitimate for a self-hosted
+ * instance and cannot change WHICH host is contacted.
+ */
+exports.HOST_FORBIDDEN_CHARS = Object.freeze([
+    '/',
+    '\\',
+    '@',
+    '?',
+    '#',
+]);
+const PROFILE_FLATTEN_DEPTH_CAP = 4;
+const PROFILE_FLATTEN_LEAF_CAP = 200;
+const PROFILE_IGNORED_WARNING_CAP = 5;
+// ─── Private helpers (deliberate per-module duplication) ────────────────────
+/**
+ * Read a dotted config key from `.planning/config.json`, returning
+ * `fallback` on any miss/unreadable-file/parse-error/non-object. Never
+ * throws. Byte-for-byte mirror of `cfgGet` in `src/vault-coordinates.cts`
+ * (lines 114-125), which itself mirrors the canonical original at
+ * `src/git-provider.cts` (lines 78-89). Written inline rather than imported
+ * — see the module header for why (the cycle this module must not create).
+ */
+function cfgGet(cwd, key, fallback) {
+    try {
+        const cfg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(cwd, '.planning', 'config.json'), 'utf-8'));
+        const v = key.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), cfg);
+        return v === undefined ? fallback : v;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Mirror of `isObject` in `src/vault-coordinates.cts` (lines 127-129). */
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Bound a rejected/untrusted config or profile value before it is echoed
+ * into a warning. Byte-for-byte mirror of `sanitizeForWarning` in
+ * `src/git-provider.cts` (lines 98-100) / `src/vault-coordinates.cts`
+ * (lines 155-157): strip CR/LF, collapse internal whitespace, trim,
+ * truncate to 40 characters (T-31-05, T-33-05).
+ */
+function sanitizeForWarning(value) {
+    return value.replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 40);
+}
+/** Bound a whole warning string to 200 characters — every warning this module
+ * emits goes through this (T-31-05). */
+function bound(warning) {
+    return warning.slice(0, 200);
+}
+/**
+ * Describe an arbitrary config-supplied value as a string for a warning,
+ * without ever calling the ambient `toString`/template-literal coercion on
+ * an object (which would silently produce `"[object Object]"`). Strings
+ * pass through; numbers/booleans coerce safely; everything else goes
+ * through `JSON.stringify`, falling back to `Object.prototype.toString`
+ * (an explicit, guaranteed-safe call, not the value's own) on failure.
+ */
+function describeUnknown(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (value === null)
+        return 'null';
+    try {
+        const serialized = JSON.stringify(value);
+        return typeof serialized === 'string' ? serialized : Object.prototype.toString.call(value);
+    }
+    catch {
+        return Object.prototype.toString.call(value);
+    }
+}
+// ─── resolveGlobalPackageRoot ────────────────────────────────────────────────
+/**
+ * D-03's "global" half of the two-path resolution ladder, as a pure
+ * heuristic with NO subprocess spawn (this repo avoids spawning a
+ * subprocess for a computation that does not strictly require one):
+ *
+ * 1. `NPM_CONFIG_PREFIX` / `npm_config_prefix`, when set to a non-blank
+ *    string: `<prefix>/node_modules` on `win32`, `<prefix>/lib/node_modules`
+ *    otherwise.
+ * 2. Otherwise, derived from `process.execPath`: with
+ *    `execDir = path.dirname(process.execPath)`, `path.join(execDir,
+ *    'node_modules')` on `win32`, `path.resolve(execDir, '..', 'lib',
+ *    'node_modules')` otherwise.
+ *
+ * The candidate is returned only when `fs.existsSync(candidate)`;
+ * otherwise `null`.
+ *
+ * Accepted residual: an nvm/Volta-style layout that honours neither
+ * `NPM_CONFIG_PREFIX` nor places the global tree beside the node binary
+ * will simply not resolve a globally-installed profile — this degrades
+ * per D-09 (falls through to the no-profile behaviour with a warning)
+ * rather than failing.
+ *
+ * pp-core's own install directory is deliberately NOT a candidate here:
+ * the AI-runtime install is a bare directory copy with no `package.json`
+ * and no `node_modules` of its own, so resolving relative to it would
+ * never find a sibling package.
+ */
+function resolveGlobalPackageRoot() {
+    try {
+        const prefixEnv = process.env.NPM_CONFIG_PREFIX ?? process.env.npm_config_prefix;
+        let candidate;
+        if (typeof prefixEnv === 'string' && prefixEnv.trim() !== '') {
+            const prefix = prefixEnv.trim();
+            candidate =
+                process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules');
+        }
+        else {
+            const execDir = node_path_1.default.dirname(process.execPath);
+            candidate =
+                process.platform === 'win32'
+                    ? node_path_1.default.join(execDir, 'node_modules')
+                    : node_path_1.default.resolve(execDir, '..', 'lib', 'node_modules');
+        }
+        return node_fs_1.default.existsSync(candidate) ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── resolveProfilePackage ───────────────────────────────────────────────────
+/**
+ * D-03's two-path resolution ladder. Attempt `require.resolve(pkgName +
+ * '/package.json', { paths: [cwd] })` first and report `source: 'project'`;
+ * on failure attempt the same with `paths: [globalRoot]` when a global root
+ * was found and report `source: 'global'`; otherwise `null`. The
+ * project-local hit always wins when both would resolve — the global
+ * attempt is only ever reached when the project attempt threw.
+ *
+ * Mirrors `resolveEslintCli` in `src/prohibition-enforcement.cts` (lines
+ * 220-228): the same try/catch-returns-null shape, one level removed
+ * (resolving a data file's sibling `package.json`, not a CLI entry point).
+ */
+function resolveProfilePackage(pkgName, cwd, globalRoot) {
+    try {
+        return { pkgJsonPath: require.resolve(`${pkgName}/package.json`, { paths: [cwd] }), source: 'project' };
+    }
+    catch {
+        // fall through to the global attempt below
+    }
+    if (globalRoot) {
+        try {
+            return { pkgJsonPath: require.resolve(`${pkgName}/package.json`, { paths: [globalRoot] }), source: 'global' };
+        }
+        catch {
+            // fall through to null below
+        }
+    }
+    return null;
+}
+/**
+ * Flatten a parsed profile document to dotted leaf paths, recursing only
+ * through plain objects. Bounded on two axes (T-33-06, denial-of-service):
+ * a depth cap of 4 and a visited-leaf cap of 200. A document exceeding
+ * either cap stops flattening immediately and reports exactly one bounded
+ * warning — the caller never sees more than one such warning regardless of
+ * how far over either cap the document goes.
+ */
+function flattenProfileDocument(doc) {
+    const leaves = [];
+    let cappedWarning = null;
+    function walk(obj, prefix, depth) {
+        if (cappedWarning)
+            return;
+        for (const k of Object.keys(obj)) {
+            if (cappedWarning)
+                return;
+            const dotted = prefix ? `${prefix}.${k}` : k;
+            const v = obj[k];
+            if (isObject(v)) {
+                if (depth + 1 > PROFILE_FLATTEN_DEPTH_CAP) {
+                    cappedWarning = 'org profile document was too deeply nested to inspect fully — stopped flattening.';
+                    return;
+                }
+                walk(v, dotted, depth + 1);
+            }
+            else {
+                if (leaves.length >= PROFILE_FLATTEN_LEAF_CAP) {
+                    cappedWarning = 'org profile document was too large to inspect fully — stopped flattening.';
+                    return;
+                }
+                leaves.push({ key: dotted, value: v });
+            }
+        }
+    }
+    walk(doc, '', 0);
+    return { leaves, cappedWarning };
+}
+// ─── profileValueDisposition (D-10) ──────────────────────────────────────────
+/**
+ * The D-10 guard: profile-supplied values pass the same scalar guard every
+ * allowlisted key gets, then a stricter per-key disposition — expressed as
+ * a DISPOSITION over the shared shape predicates, never as a parallel
+ * regex (D-10's "one source of shape truth" requirement).
+ *
+ * Scalar guard, applied to every key: the value must be a string; its
+ * trimmed form must be non-empty; the UNTRIMMED value must carry no ASCII
+ * control character; the TRIMMED value must carry no whitespace (so
+ * leading/trailing padding — e.g. `' azure '` — is tolerated, matching
+ * every other config reader in this seam, but an internal space or newline
+ * is not); and the trimmed value must not start with `-` (the T-29-26
+ * flag-shaped refusal `isLiteralCloneTarget` already applies at
+ * `src/git-provider.cts:186`, restated here as a disposition because a
+ * plain slug beginning with `-` is not a literal clone target and would
+ * otherwise pass `isLiteralCloneTarget` unmolested). The value carried
+ * forward past the scalar guard is always the trimmed string.
+ *
+ * Per-key dispositions:
+ * - `vault.provider`: accept only when `normalizeProvider(value)` (obtained
+ *   via the call-time lazy `require('./git-provider.cjs')`, never a
+ *   top-level import) returns non-null, and carry forward the NORMALIZED
+ *   id. Reason on failure names the supported ids via `PROVIDERS`.
+ * - `vault.fallback_repo`: reject when the trimmed value matches any of
+ *   `PROFILE_REJECTED_CLONE_TARGET_PATTERNS`. Everything else — an
+ *   absolute path, a scheme URL, scp-style `user@host:path`, or a plain
+ *   `group/project` slug — is accepted UNCHANGED (T-30-08: never rewritten,
+ *   normalised or stripped).
+ * - `vault.fallback_host` / `platform.host`: reject when the trimmed value
+ *   contains any of `/` `\` `@` `?` `#` — these values are interpolated
+ *   into a clone URL by `composeCloneTarget` as the AUTHORITY component,
+ *   so the guard has to keep the value from carrying a path AND from
+ *   escaping the authority at all. `@` is the load-bearing one: a host of
+ *   `dev.azure.com@attacker.example.com` composes to
+ *   `https://dev.azure.com@attacker.example.com/…`, which every RFC-3986
+ *   parser reads as userinfo `dev.azure.com` at host `attacker.example.com`
+ *   — a dependency-supplied value silently redirecting the clone, and with
+ *   it the `(repo, host)` pair `assertVaultWriteTarget` decides on. `?` and
+ *   `#` likewise terminate the authority early. None is legal in a
+ *   hostname. `:` is deliberately still allowed: a port is legitimate for
+ *   a self-hosted instance and cannot change WHICH host is contacted.
+ * - `vault.fallback_ref`: the scalar guard alone.
+ *
+ * Wrapped so that any unexpected fault (including a `require` failure on
+ * the lazy seam) degrades to rejecting the value rather than throwing
+ * (D-09) — this function never throws.
+ */
+function profileValueDisposition(key, value) {
+    try {
+        if (typeof value !== 'string') {
+            return { ok: false, reason: 'value must be a string' };
+        }
+        const trimmed = value.trim();
+        if (trimmed === '') {
+            return { ok: false, reason: 'value must not be blank' };
+        }
+        if (/[\x00-\x1f\x7f]/.test(value)) {
+            return { ok: false, reason: 'value must not contain control characters' };
+        }
+        if (/\s/.test(trimmed)) {
+            return { ok: false, reason: 'value must not contain whitespace' };
+        }
+        if (trimmed.startsWith('-')) {
+            return { ok: false, reason: 'value must not begin with "-"' };
+        }
+        if (key === 'vault.provider') {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const gp = require('./git-provider.cjs');
+            const normalized = gp.normalizeProvider(trimmed);
+            if (normalized === null) {
+                return { ok: false, reason: `unsupported provider — supported: ${gp.PROVIDERS.join(', ')}` };
+            }
+            return { ok: true, value: normalized };
+        }
+        if (key === 'vault.fallback_repo') {
+            if (compiledRejectedCloneTargetPatterns.some((re) => re.test(trimmed))) {
+                return { ok: false, reason: 'a machine-specific path is not accepted from an org profile' };
+            }
+            return { ok: true, value: trimmed };
+        }
+        if (key === 'vault.fallback_host' || key === 'platform.host') {
+            // Authority-escape guard. `/` and `\` keep a path out of the value;
+            // `@` `?` `#` keep the value from redirecting or truncating the
+            // authority component it is interpolated into. See the doc block.
+            for (const ch of exports.HOST_FORBIDDEN_CHARS) {
+                if (trimmed.includes(ch)) {
+                    return {
+                        ok: false,
+                        reason: `a host must not contain ${ch} — it must be a bare host, optionally with a port`,
+                    };
+                }
+            }
+            return { ok: true, value: trimmed };
+        }
+        // vault.fallback_ref: the scalar guard alone.
+        return { ok: true, value: trimmed };
+    }
+    catch {
+        return { ok: false, reason: 'value could not be validated' };
+    }
+}
+// ─── resolveOrgProfileDocument (D-01) ────────────────────────────────────────
+/**
+ * Resolve the org profile configured (if any) for the project at `cwd`, and
+ * return the RAW parsed document — unflattened, unfiltered, including any
+ * `ORG_PROFILE_SEED_SECTION` the D-06 allowlist deliberately excludes.
+ *
+ * This is `resolveOrgProfile`'s own pointer→package→document walk (its
+ * former steps 1-3), extracted so the two have exactly ONE implementation of
+ * that walk (the WR-01 defect class this repo has already paid for twice) —
+ * `resolveOrgProfile` calls this function for its own steps 1-3 rather than
+ * duplicating them. Consumers that need the D-06-filtered `contributes` map
+ * still want `resolveOrgProfile`; this function exists for the Phase 34
+ * bindings composer, which needs the seed section `resolveOrgProfile`
+ * deliberately never surfaces.
+ *
+ * The `_globalRoot` option is the repo's `_`-prefixed test seam convention
+ * (as used by `_vault` / `_exec` / `_writeBack` in
+ * `src/vault-command-router.cts`); production callers omit it and the
+ * module calls `resolveGlobalPackageRoot()`. Passing `_globalRoot`
+ * explicitly (including `null`, to simulate "no global root found")
+ * overrides the production heuristic for that one call.
+ *
+ * Never throws (D-09): any fault anywhere in this function degrades to the
+ * fully-absent shape plus one bounded warning, exactly as if no profile
+ * were configured. The document is read only via `fs.readFileSync` +
+ * `JSON.parse`, never `require` (D-08).
+ */
+function resolveOrgProfileDocument(cwd, opts) {
+    const absentDocShape = (warnings = []) => ({
+        configured: null,
+        resolved: false,
+        packageName: null,
+        version: null,
+        source: 'none',
+        dataPath: null,
+        document: {},
+        warnings,
+    });
+    try {
+        // Step 1: read the pointer. An absent key (undefined) or a blank string
+        // is the fully-absent shape with ZERO warnings and no further
+        // filesystem access — this is the ORG-02 contract. A present
+        // non-string value is the one exception: same absent shape, plus
+        // exactly one bounded warning.
+        const rawPointer = cfgGet(cwd, exports.ORG_PROFILE_CONFIG_KEY, undefined);
+        if (rawPointer === undefined) {
+            return absentDocShape();
+        }
+        if (typeof rawPointer !== 'string') {
+            const echoed = sanitizeForWarning(describeUnknown(rawPointer));
+            return absentDocShape([
+                bound(`${exports.ORG_PROFILE_CONFIG_KEY} value "${echoed}" is not a string — ignoring, no org profile applied.`),
+            ]);
+        }
+        const pkgName = rawPointer.trim();
+        if (pkgName === '') {
+            return absentDocShape();
+        }
+        // Step 2: resolve the package (project, then global).
+        const globalRoot = opts && opts._globalRoot !== undefined ? opts._globalRoot : resolveGlobalPackageRoot();
+        const hit = resolveProfilePackage(pkgName, cwd, globalRoot);
+        if (!hit) {
+            const echoed = sanitizeForWarning(pkgName);
+            return {
+                ...absentDocShape(),
+                configured: pkgName,
+                warnings: [
+                    bound(`org profile "${echoed}" was not found — resolution was attempted from the project and the global npm root and found nothing. Falling back to built-in defaults.`),
+                ],
+            };
+        }
+        const packageDir = node_path_1.default.dirname(hit.pkgJsonPath);
+        // Step 3: read the package's own version, then its data file. NEVER
+        // load the profile package or any file inside it via `require` (D-08) —
+        // only require.resolve (path resolution), fs.readFileSync and JSON.parse.
+        let version = null;
+        try {
+            const pkgJson = JSON.parse(node_fs_1.default.readFileSync(hit.pkgJsonPath, 'utf-8'));
+            version = isObject(pkgJson) && typeof pkgJson.version === 'string' ? pkgJson.version : null;
+        }
+        catch {
+            version = null;
+        }
+        const dataPath = node_path_1.default.join(packageDir, exports.ORG_PROFILE_DATA_FILE);
+        const warnings = [];
+        let doc = {};
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(dataPath, 'utf-8'));
+            if (isObject(parsed)) {
+                doc = parsed;
+            }
+            else {
+                warnings.push(bound(`org profile "${pkgName}" data file is not a JSON object — no coordinates contributed.`));
+            }
+        }
+        catch {
+            warnings.push(bound(`org profile "${pkgName}" data file could not be read — no coordinates contributed.`));
+        }
+        return {
+            configured: pkgName,
+            resolved: true,
+            packageName: pkgName,
+            version,
+            source: hit.source,
+            dataPath,
+            document: doc,
+            warnings,
+        };
+    }
+    catch {
+        return absentDocShape(['org profile resolution failed unexpectedly — falling back to built-in defaults.']);
+    }
+}
+// ─── resolveOrgProfile ────────────────────────────────────────────────────────
+/**
+ * Resolve the org profile configured (if any) for the project at `cwd`.
+ *
+ * Delegates its own steps 1-3 (pointer → package → raw document) to
+ * `resolveOrgProfileDocument` — see that function's doc comment for the
+ * `_globalRoot` test seam and the D-09 never-throws contract, both of which
+ * this function inherits unchanged.
+ *
+ * Never throws (D-09): any fault anywhere in this function degrades to the
+ * fully-absent shape plus one bounded warning, exactly as if no profile
+ * were configured.
+ */
+function resolveOrgProfile(cwd, opts) {
+    const absentShape = (warnings = []) => ({
+        configured: null,
+        resolved: false,
+        packageName: null,
+        version: null,
+        source: 'none',
+        dataPath: null,
+        contributes: {},
+        ignored: [],
+        rejected: [],
+        warnings,
+    });
+    try {
+        const docResolution = resolveOrgProfileDocument(cwd, opts);
+        // Steps 1-3 absent (no pointer, non-string pointer, blank pointer, or
+        // package not found): carry the document resolution's `configured` and
+        // `warnings` through verbatim into the absent-shaped OrgProfileResolution.
+        if (!docResolution.resolved) {
+            return {
+                ...absentShape(docResolution.warnings),
+                configured: docResolution.configured,
+            };
+        }
+        const warnings = [...docResolution.warnings];
+        const doc = docResolution.document;
+        // Step 4: flatten and partition by the allowlist (D-06).
+        const { leaves, cappedWarning } = flattenProfileDocument(doc);
+        if (cappedWarning)
+            warnings.push(bound(cappedWarning));
+        const contributes = {};
+        const ignored = [];
+        const rejected = [];
+        let ignoredWarningCount = 0;
+        let ignoredOverflow = 0;
+        // Step 5: validate each allowlisted leaf (D-10); everything else is
+        // dropped with a capped warning list (D-06) — except the seed namespace
+        // (D-01), which is a KNOWN non-runtime namespace with its own composer
+        // (Phase 34), not an unknown key. Skipping it here means it never
+        // consumes the PROFILE_IGNORED_WARNING_CAP budget and never makes a
+        // seeded profile's `resolveProvider` / `vault status` calls noisier —
+        // and it changes no membership in ORG_PROFILE_ALLOWLIST.
+        for (const leaf of leaves) {
+            if (leaf.key === exports.ORG_PROFILE_SEED_SECTION || leaf.key.startsWith(`${exports.ORG_PROFILE_SEED_SECTION}.`)) {
+                continue;
+            }
+            if (!exports.ORG_PROFILE_ALLOWLIST.includes(leaf.key)) {
+                ignored.push(leaf.key);
+                if (ignoredWarningCount < PROFILE_IGNORED_WARNING_CAP) {
+                    warnings.push(bound(`org profile key "${sanitizeForWarning(leaf.key)}" is not on the allowlist — ignored.`));
+                    ignoredWarningCount += 1;
+                }
+                else {
+                    ignoredOverflow += 1;
+                }
+                continue;
+            }
+            const disposition = profileValueDisposition(leaf.key, leaf.value);
+            if (disposition.ok) {
+                contributes[leaf.key] = disposition.value;
+            }
+            else {
+                rejected.push(leaf.key);
+                warnings.push(bound(`org profile key "${leaf.key}" rejected — ${disposition.reason}.`));
+            }
+        }
+        if (ignoredOverflow > 0) {
+            warnings.push(bound(`${ignoredOverflow} further org profile key(s) were ignored (not on the allowlist).`));
+        }
+        // Step 6: return. Nothing above throws for any input, but the whole
+        // body is still guarded below (D-09) so a fault in a helper this
+        // function forgot to wrap still yields the absent shape, not a crash.
+        return {
+            configured: docResolution.configured,
+            resolved: true,
+            packageName: docResolution.packageName,
+            version: docResolution.version,
+            source: docResolution.source,
+            dataPath: docResolution.dataPath,
+            contributes,
+            ignored,
+            rejected,
+            warnings,
+        };
+    }
+    catch {
+        return absentShape(['org profile resolution failed unexpectedly — falling back to built-in defaults.']);
+    }
+}
+// ─── readProfileValue (D-07) ──────────────────────────────────────────────────
+/**
+ * D-07's key-keyed profile layer. This function REPLACES the tier-keyed
+ * `orgProfileCoordinates(cwd, tier)` stub Phase 31 froze in
+ * `src/vault-coordinates.cts` — a deliberate supersession, not an
+ * extension, recorded here and in `src/vault-coordinates.cts`'s own doc
+ * comment. D-06's allowlist is a set of config KEYS, not tiers, so one
+ * key-keyed function serves all three consuming resolvers
+ * (`resolveSharedCoordinates`, `resolvePlatformHost`, and
+ * `resolveProvider`), where `provider` and `platform.host` do not fit a
+ * per-tier return shape at all. `resolveClientCoordinates` needs no direct
+ * call: its host chain reaches this function transitively through
+ * `resolvePlatformHost`.
+ *
+ * When `key` is not in `ORG_PROFILE_ALLOWLIST`, returns
+ * `{ value: undefined, warnings: [], source: 'none' }` immediately with NO
+ * filesystem access — a caller asking for a non-allowlisted key is a
+ * programming error in this module's own consumers, not an untrusted-input
+ * case. Otherwise resolves the profile via `resolveOrgProfile(cwd, opts)`
+ * and returns that key's `contributes` entry (or `undefined`), the
+ * resolution's `warnings`, and its `source`.
+ *
+ * The profile is re-read from disk on every call, matching every sibling
+ * resolver in this seam (`cfgGet`, `readBindings`, `resolveProvider`) —
+ * this module introduces no caching. Consumers that call this more than
+ * once per resolution MUST de-duplicate the returned warnings by exact
+ * string before folding them into their own warning list.
+ */
+function readProfileValue(cwd, key, opts) {
+    if (!exports.ORG_PROFILE_ALLOWLIST.includes(key)) {
+        return { value: undefined, warnings: [], source: 'none' };
+    }
+    const resolution = resolveOrgProfile(cwd, opts);
+    return {
+        value: resolution.contributes[key],
+        warnings: resolution.warnings,
+        source: resolution.source,
+    };
+}