@pareto4/pp-core 1.9.0 → 1.11.0

package/pp-core/bin/lib/compose-bindings.cjs

@@ -0,0 +1,736 @@
+"use strict";
+/**
+ * src/compose-bindings.cts — the bindings composer (milestone v1.11.0, Phase 34-03).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/compose-bindings.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is locked by
+ * `tests/compose-bindings.test.cjs`.
+ *
+ * This module reads the D-01 seed section an org profile package may carry
+ * (`bindings.*`, read via `resolveOrgProfileDocument` — never
+ * `readProfileValue`, whose allowlist gate deliberately excludes the seed
+ * namespace) plus the project answers `/pp-init` already captured in
+ * `.planning/config.json`, composes a `.platform-bindings.json` candidate,
+ * delegates every shape rule to `validateBindings` (never a second regex for
+ * `platform.repo`/`client.vaultRepo`/`client.slug`/`project.slug`/`platform.tag`),
+ * pins `platform.tag` to the seeded platform's latest stable tag over the
+ * resolved host, merges absent keys only against any existing file, and
+ * writes only when explicitly told to (`opts.write === true`). Dry-run is the
+ * no-flag default (D-10) — `composeBindings` and `cmdComposeBindings` share
+ * this exact code path with no second implementation for the `/pp-init` call
+ * site.
+ *
+ * D-05 puts this composition in a CLI arm rather than `init.md` shell: the
+ * CLI-writer + `.md` shell-glue seam is a known blindspot in this repo —
+ * `node:test` covers the writer while the heredoc JSON and the parsed-key
+ * round-trip go untested, and that is exactly how the
+ * `generate-client-context` CR-02 bug shipped. A file that governs the vault
+ * write guard must not be assembled where the suite cannot reach it. Every
+ * JSON object this module writes is built in compiled code via
+ * `JSON.stringify`/object literals — never by `.md` shell string
+ * concatenation.
+ *
+ * This module sits at the top of the CommonJS graph — nothing imports it —
+ * so its top-level imports of `./org-profile.cjs`, `./platform-bindings.cjs`,
+ * `./git-provider.cjs`, `./vault-coordinates.cjs`, `./io.cjs`,
+ * `./project-root.cjs`, `./package-identity.cjs` and
+ * `./shell-command-projection.cjs` create no require cycle: none of those
+ * modules imports this one, at load time or lazily.
+ *
+ * Like `src/org-profile.cts`, this file's own prose and code deliberately
+ * never name a concrete client or a concrete org profile package.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPOSE_BINDINGS_FLAGS = exports.SEED_VALUE_MAX_LENGTH = void 0;
+exports.composeBindings = composeBindings;
+exports.cmdComposeBindings = cmdComposeBindings;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = __importDefault(require("node:child_process"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output } = io;
+const project_root_cjs_1 = require("./project-root.cjs");
+const package_identity_cjs_1 = require("./package-identity.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const semver_compare_cjs_1 = require("./semver-compare.cjs");
+const org_profile_cjs_1 = require("./org-profile.cjs");
+const platform_bindings_cjs_1 = require("./platform-bindings.cjs");
+const git_provider_cjs_1 = require("./git-provider.cjs");
+const vault_coordinates_cjs_1 = require("./vault-coordinates.cjs");
+// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * The maximum accepted length of a seed value. Rejecting a value past this
+ * bound is preferred to truncating it: a truncated coordinate that still got
+ * written would be a silently wrong clone target.
+ */
+exports.SEED_VALUE_MAX_LENGTH = 200;
+/**
+ * D-03's required core: any of these failing means compose nothing. Every
+ * other field `validateBindings` might reject is OPTIONAL — dropped with a
+ * warning rather than blocking the whole compose.
+ */
+const REQUIRED_ERROR_PREFIXES = Object.freeze(['root', 'schemaVersion', 'platform', 'platform.repo']);
+/** Maps each D-01 seed key (fully dotted, `ORG_PROFILE_SEED_SECTION`-prefixed)
+ * to the short name this module carries it under internally. */
+const SEED_KEY_SHORT_NAMES = Object.freeze({
+    [`${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.platform.repo`]: 'platformRepo',
+    [`${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.client.vaultRepo`]: 'clientVaultRepo',
+    [`${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.client.vaultRef`]: 'clientVaultRef',
+    [`${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.client.vaultHost`]: 'clientVaultHost',
+    [`${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.provisioning.group`]: 'provisioningGroup',
+});
+// Compiled once at module load, without the global flag (a global regex
+// carries `lastIndex` state across `test` calls) — the same convention
+// `src/git-provider.cts` and `src/org-profile.cts` both use for their own
+// copies of this array. Imported, never re-typed (T-34-21).
+const compiledRejectedCloneTargetPatterns = org_profile_cjs_1.PROFILE_REJECTED_CLONE_TARGET_PATTERNS.map((source) => new RegExp(source));
+/** The recognized flag set for the `compose-bindings` CLI arm (34-04's
+ * fail-fast unrecognized-flag guard reads this). */
+exports.COMPOSE_BINDINGS_FLAGS = Object.freeze(['--write', '--offline']);
+// ─── Private helpers (deliberate per-module duplication, canonical originals
+// named in each comment) ──────────────────────────────────────────────────────
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isUsableString(v) {
+    return typeof v === 'string' && v.trim() !== '';
+}
+/** Byte-for-byte mirror of `sanitizeForWarning` in `src/git-provider.cts`
+ * (lines 98-100): strip CR/LF, collapse internal whitespace, trim, truncate
+ * to 40 characters. */
+function sanitizeForWarning(value) {
+    return value.replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 40);
+}
+/** Bound a whole warning string to 200 characters, mirroring `bound` in
+ * `src/org-profile.cts` (line 196-249). */
+function bound(warning) {
+    return warning.slice(0, 200);
+}
+/** Byte-for-byte mirror of `cfgGet` in `src/git-provider.cts` (lines 78-89).
+ * Written inline rather than imported for the same require-cycle reason
+ * every sibling seam module inlines this reader. */
+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;
+    }
+}
+/** Append only strings not already present in `target` — mirrors
+ * `pushDeduped` in `src/vault-coordinates.cts` (lines 200-204). This module
+ * can consult the org profile and the host resolver multiple times per call;
+ * D-09 promises one bounded warning per rejected thing, not several copies. */
+function pushDeduped(target, incoming) {
+    for (const w of incoming) {
+        if (!target.includes(w))
+            target.push(w);
+    }
+}
+// ─── Dotted-path object helpers (bounded, depth matches the schema's own
+// shallow shape — top-level namespace, one leaf level) ────────────────────────
+function hasNestedOwn(obj, dottedPath) {
+    if (!obj)
+        return false;
+    const parts = dottedPath.split('.');
+    let cur = obj;
+    for (const p of parts) {
+        if (!isObject(cur) || !Object.prototype.hasOwnProperty.call(cur, p))
+            return false;
+        cur = cur[p];
+    }
+    return true;
+}
+function getNested(obj, dottedPath) {
+    if (!obj)
+        return undefined;
+    const parts = dottedPath.split('.');
+    let cur = obj;
+    for (const p of parts) {
+        if (!isObject(cur))
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+function setNested(obj, dottedPath, value) {
+    const parts = dottedPath.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        if (!isObject(cur[key]))
+            cur[key] = {};
+        cur = cur[key];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+function deleteDottedField(obj, dottedPath) {
+    const parts = dottedPath.split('.');
+    if (parts.length === 1) {
+        delete obj[parts[0]];
+        return;
+    }
+    const parent = obj[parts[0]];
+    if (isObject(parent)) {
+        delete parent[parts[1]];
+        if (Object.keys(parent).length === 0)
+            delete obj[parts[0]];
+    }
+}
+function deepCloneJsonSafe(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+/** Flatten a plain object to dotted leaf paths, bounded at depth 6 (the
+ * schema's own real depth is 2; the bound exists only so a pathological
+ * hand-edited file cannot recurse unbounded). */
+function walkLeaves(obj, prefix, depthCap, out) {
+    if (depthCap <= 0)
+        return;
+    for (const k of Object.keys(obj)) {
+        const dotted = prefix ? `${prefix}.${k}` : k;
+        const v = obj[k];
+        if (isObject(v)) {
+            walkLeaves(v, dotted, depthCap - 1, out);
+        }
+        else {
+            out.push({ path: dotted, value: v });
+        }
+    }
+}
+function hasAnyNewKey(composed, existing) {
+    const leaves = [];
+    walkLeaves(composed, '', 6, leaves);
+    return leaves.some((leaf) => !hasNestedOwn(existing, leaf.path));
+}
+// ─── dispositionSeedValue (D-03 seed guard) ──────────────────────────────────
+/**
+ * Guard a single D-01 seed value, never throwing. Scalar guard first
+ * (mirroring `profileValueDisposition` in `src/org-profile.cts`): must be a
+ * string; the trimmed form non-empty; the UNTRIMMED value carries no ASCII
+ * control character; the TRIMMED value carries no whitespace; the trimmed
+ * value does not begin with `-`; the trimmed length is at most
+ * `SEED_VALUE_MAX_LENGTH`. Then a per-key disposition built entirely from
+ * imported constants — this function authors no new pattern strings.
+ *
+ * `seedKey` is the FULLY DOTTED key (`ORG_PROFILE_SEED_SECTION`-prefixed,
+ * e.g. `bindings.client.vaultHost`), matching the entries of
+ * `ORG_PROFILE_SEED_KEYS`.
+ */
+function dispositionSeedValue(seedKey, 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 (trimmed.length > exports.SEED_VALUE_MAX_LENGTH) {
+            return { ok: false, reason: `value exceeds the maximum accepted length of ${exports.SEED_VALUE_MAX_LENGTH} characters` };
+        }
+        if (seedKey === `${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.client.vaultHost`) {
+            // Authority-escape guard (T-34-20) — genuinely new surface:
+            // `profileValueDisposition` only ever runs inside the allowlist-gated
+            // walk and gives a seed key nothing for free.
+            for (const ch of org_profile_cjs_1.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 };
+        }
+        if (seedKey === `${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.platform.repo` ||
+            seedKey === `${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.client.vaultRepo` ||
+            seedKey === `${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.provisioning.group`) {
+            // T-34-21: a machine-specific clone target is not accepted from a
+            // package — a human chose one deliberately and a package did not.
+            if (compiledRejectedCloneTargetPatterns.some((re) => re.test(trimmed))) {
+                return { ok: false, reason: 'a machine-specific path is not accepted from an org profile' };
+            }
+            if (seedKey === `${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.provisioning.group`) {
+                const segments = trimmed.split('/');
+                if (trimmed.startsWith('/') || segments.includes('..')) {
+                    return { ok: false, reason: 'value must not begin with "/" or contain a ".." path segment' };
+                }
+            }
+            return { ok: true, value: trimmed };
+        }
+        // bindings.client.vaultRef: the scalar guard alone.
+        return { ok: true, value: trimmed };
+    }
+    catch {
+        return { ok: false, reason: 'value could not be validated' };
+    }
+}
+/**
+ * Read the D-01 seed section through `resolveOrgProfileDocument` — never
+ * `readProfileValue`, whose allowlist gate would return `undefined` with no
+ * filesystem access for a seed key and would misrepresent the boundary.
+ * Walks exactly the members of `ORG_PROFILE_SEED_KEYS` (never an open-ended
+ * walk), running each present value through `dispositionSeedValue`.
+ */
+function readSeed(cwd, opts) {
+    const doc = (0, org_profile_cjs_1.resolveOrgProfileDocument)(cwd, opts);
+    const profile = {
+        resolved: doc.resolved,
+        packageName: doc.packageName,
+        version: doc.version,
+        source: doc.source,
+        dataPath: doc.dataPath,
+    };
+    const warnings = [...doc.warnings];
+    const values = {};
+    const seedSectionRaw = doc.document[org_profile_cjs_1.ORG_PROFILE_SEED_SECTION];
+    if (!doc.resolved) {
+        return { values, profile, warnings };
+    }
+    if (!isObject(seedSectionRaw)) {
+        if (seedSectionRaw !== undefined) {
+            warnings.push(bound(`org profile "${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}" section is not a JSON object — no coordinates seeded.`));
+        }
+        return { values, profile, warnings };
+    }
+    for (const dottedKey of org_profile_cjs_1.ORG_PROFILE_SEED_KEYS) {
+        const relPath = dottedKey.slice(org_profile_cjs_1.ORG_PROFILE_SEED_SECTION.length + 1);
+        if (!hasNestedOwn(seedSectionRaw, relPath))
+            continue;
+        const rawValue = getNested(seedSectionRaw, relPath);
+        const disposition = dispositionSeedValue(dottedKey, rawValue);
+        const shortName = SEED_KEY_SHORT_NAMES[dottedKey];
+        if (disposition.ok) {
+            values[shortName] = disposition.value;
+        }
+        else {
+            warnings.push(bound(`org profile seed key "${dottedKey}" rejected — ${disposition.reason}.`));
+        }
+    }
+    return { values, profile, warnings };
+}
+// ─── resolveLatestPlatformTag (D-04) ─────────────────────────────────────────
+/**
+ * Resolve the latest STABLE tag for `repo` over the resolved host, never
+ * shell-eval'd (T-34-25): `git ls-remote` is spawned with an argv array via
+ * `childProcess.execFileSync`, bounded by `timeout`/`maxBuffer`/`windowsHide`
+ * (T-34-26). The host is `resolvePlatformHost(cwd).host` when it resolves,
+ * else `defaultHostForProvider(provider)` — the host is authoritative and
+ * never derived from the repo string (Phase 31 D-09).
+ *
+ * Every candidate ref is filtered with `isStableTripletSemver` and ordered
+ * with `compareSemverCore` — the single blessed comparison source, never
+ * reimplemented. An empty result degrades to `{ tag: null, warnings: [] }`
+ * (tagless is valid, D-01/D-02); any thrown fault (offline, unreachable,
+ * DNS failure, non-zero git exit) degrades to `{ tag: null, warnings: [one
+ * bounded warning] }` — offline, unreachable and tagless all resolve to the
+ * platform being unpinned, never a compose failure.
+ */
+function resolveLatestPlatformTag(cwd, repo, provider, opts) {
+    try {
+        const hostRes = (0, vault_coordinates_cjs_1.resolvePlatformHost)(cwd);
+        const host = hostRes.host ?? (0, vault_coordinates_cjs_1.defaultHostForProvider)(provider);
+        const url = `https://${host}/${repo}`;
+        const lsOutput = typeof opts._lsRemote === 'function'
+            ? opts._lsRemote(url)
+            : node_child_process_1.default.execFileSync('git', ['ls-remote', '--tags', '--refs', '--sort=-v:refname', url, 'v*'], { encoding: 'utf-8', timeout: 10_000, maxBuffer: 512 * 1024, windowsHide: true });
+        const tags = lsOutput
+            .split('\n')
+            .map((line) => {
+            const m = line.match(/\brefs\/tags\/([^\s^]+)$/);
+            return m ? m[1].trim() : '';
+        })
+            .filter((t) => t && (0, semver_compare_cjs_1.isStableTripletSemver)(t));
+        if (tags.length === 0) {
+            return { tag: null, warnings: [] };
+        }
+        let latest = tags[0];
+        for (const t of tags) {
+            if ((0, semver_compare_cjs_1.compareSemverCore)(t, latest) > 0)
+                latest = t;
+        }
+        return { tag: latest, warnings: [] };
+    }
+    catch {
+        return {
+            tag: null,
+            warnings: [
+                bound('platform.tag could not be resolved — the tag lookup failed or was unreachable; the platform is unpinned.'),
+            ],
+        };
+    }
+}
+/**
+ * Read the first readable, semver-shaped `VERSION` file among the installed
+ * `pp-core/VERSION` location and this repo's own root `VERSION`, returning
+ * `<binName>@<version>`; when neither is readable, `binName` alone.
+ */
+function resolveCreatedWith() {
+    const candidates = [node_path_1.default.join(__dirname, '..', 'VERSION'), node_path_1.default.join(__dirname, '..', '..', '..', 'VERSION')];
+    for (const candidate of candidates) {
+        try {
+            const raw = node_fs_1.default.readFileSync(candidate, 'utf-8').trim();
+            if (/^\d+\.\d+\.\d+/.test(raw)) {
+                return `${package_identity_cjs_1.binName}@${raw}`;
+            }
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return package_identity_cjs_1.binName;
+}
+/**
+ * Build the composed candidate object from the seed, the project answers
+ * `/pp-init` already captured, the resolved platform host, the D-04 tag pin,
+ * the package identity and the contract version. Omits any field whose
+ * source value is absent, blank or non-string — never writes an empty
+ * string. Every emitted field is one the schema's `additionalProperties:
+ * false` property sets already allow.
+ */
+function composeCandidate(cwd, seed, provider, opts) {
+    const candidate = {};
+    const provenance = {};
+    const warnings = [];
+    const setField = (field, value, source) => {
+        if (!isUsableString(value))
+            return;
+        setNested(candidate, field, value);
+        provenance[field] = source;
+    };
+    // schemaVersion (contract) — always present, never a second '1.1.0' literal.
+    candidate.schemaVersion = platform_bindings_cjs_1.CONTRACT_SCHEMA_VERSION;
+    provenance.schemaVersion = 'contract';
+    // platform.repo (profile-seed)
+    setField('platform.repo', seed.platformRepo, 'profile-seed');
+    // platform.host (resolved-host) — one of the five runtime-allowlisted keys;
+    // sourced from the runtime resolver rather than duplicated into the seed
+    // section.
+    const hostRes = (0, vault_coordinates_cjs_1.resolvePlatformHost)(cwd);
+    pushDeduped(warnings, hostRes.warnings);
+    setField('platform.host', hostRes.host ?? undefined, 'resolved-host');
+    // platform.tag (resolved-tag, D-04) — only attempted when platform.repo
+    // composed and the caller did not opt out via offline.
+    const platformObj = candidate.platform;
+    const platformRepoValue = isObject(platformObj) ? platformObj.repo : undefined;
+    if (isUsableString(platformRepoValue) && opts.offline !== true) {
+        const tagResult = resolveLatestPlatformTag(cwd, platformRepoValue, provider, opts);
+        pushDeduped(warnings, tagResult.warnings);
+        if (tagResult.tag) {
+            setField('platform.tag', tagResult.tag, 'resolved-tag');
+        }
+    }
+    // client.name / client.slug (project-answer)
+    setField('client.name', cfgGet(cwd, 'project.client_name', undefined), 'project-answer');
+    setField('client.slug', cfgGet(cwd, 'project.client_slug', undefined), 'project-answer');
+    // client.vaultRepo / vaultRef / vaultHost (profile-seed)
+    setField('client.vaultRepo', seed.clientVaultRepo, 'profile-seed');
+    setField('client.vaultRef', seed.clientVaultRef, 'profile-seed');
+    setField('client.vaultHost', seed.clientVaultHost, 'profile-seed');
+    // project.name / project.slug (project-answer)
+    setField('project.name', cfgGet(cwd, 'project.name', undefined), 'project-answer');
+    setField('project.slug', cfgGet(cwd, 'project.slug', undefined), 'project-answer');
+    // project.createdWith (package-identity)
+    setField('project.createdWith', resolveCreatedWith(), 'package-identity');
+    return { candidate, provenance, warnings };
+}
+// ─── validateAndDispose (D-03) ────────────────────────────────────────────────
+function leadingToken(errorMsg) {
+    const idx = errorMsg.indexOf(':');
+    return idx === -1 ? errorMsg : errorMsg.slice(0, idx);
+}
+/**
+ * Implement D-03 exactly. Every shape rule comes from `validateBindings`;
+ * this function contains no second regex for any binding field.
+ *
+ * - Valid as-is: composable, unchanged.
+ * - Any REQUIRED field failing (`root`, `schemaVersion`, `platform`,
+ *   `platform.repo`): compose nothing. This asymmetry is load-bearing — the
+ *   presence of `.platform-bindings.json` is itself the gate that flips
+ *   `/pp-init` and `execute-phase` into Pareto mode, so writing a file with
+ *   an unusable `platform.repo` would flip that gate into a state nothing
+ *   downstream can satisfy.
+ * - Otherwise (only OPTIONAL fields failing): a field whose provenance is
+ *   `existing-file` is NEVER deleted (T-30-08) — when only such fields fail,
+ *   report `composable: false` naming them. Otherwise delete each failing
+ *   optional field (and its parent when it becomes empty), warn once per
+ *   field, and re-validate ONCE. If still invalid, `composable: false`.
+ */
+function validateAndDispose(candidate, provenanceByField) {
+    const first = (0, platform_bindings_cjs_1.validateBindings)(candidate);
+    if (first.valid) {
+        return { composable: true, composed: candidate, warnings: [] };
+    }
+    const failingFields = first.errors.map(leadingToken);
+    const requiredFailures = failingFields.filter((f) => REQUIRED_ERROR_PREFIXES.includes(f));
+    if (requiredFailures.length > 0) {
+        const requiredErrorText = first.errors
+            .filter((e) => REQUIRED_ERROR_PREFIXES.includes(leadingToken(e)))
+            .join('; ');
+        return {
+            composable: false,
+            composed: null,
+            warnings: [bound(`binding could not be composed — required field(s) invalid: ${requiredErrorText}`)],
+        };
+    }
+    const uneditableFields = failingFields.filter((f) => provenanceByField[f] === 'existing-file');
+    if (uneditableFields.length > 0) {
+        return {
+            composable: false,
+            composed: null,
+            warnings: [
+                bound(`binding could not be composed — the existing .platform-bindings.json has invalid value(s) for ${sanitizeForWarning(uneditableFields.join(', '))}; fix the committed file directly.`),
+            ],
+        };
+    }
+    const mutated = deepCloneJsonSafe(candidate);
+    const warnings = [];
+    for (let i = 0; i < first.errors.length; i++) {
+        const field = failingFields[i];
+        warnings.push(bound(`${field} dropped from composed binding — ${first.errors[i]}`));
+        deleteDottedField(mutated, field);
+    }
+    const second = (0, platform_bindings_cjs_1.validateBindings)(mutated);
+    if (!second.valid) {
+        return {
+            composable: false,
+            composed: null,
+            warnings: [...warnings, bound('binding still invalid after dropping optional fields — composing nothing.')],
+        };
+    }
+    return { composable: true, composed: mutated, warnings };
+}
+/**
+ * Read `<cwd>/.platform-bindings.json`. Absent → `present: false`. Present
+ * and a parseable JSON object → `present: true, malformed: false`. Present
+ * but malformed JSON or not a JSON object → `present: true, malformed: true`
+ * with one bounded warning; this deliberately does NOT adopt
+ * `cmdPlatformBindings`' hard-error-on-malformed-JSON behaviour — this arm
+ * reports a verdict as data on exit 0, and an unreadable file is a reason to
+ * do nothing rather than a reason to crash a `/pp-init` run.
+ */
+function readExistingBindings(cwd) {
+    const bindingsPath = node_path_1.default.join(cwd, '.platform-bindings.json');
+    if (!node_fs_1.default.existsSync(bindingsPath)) {
+        return { present: false, malformed: false, data: {}, warnings: [] };
+    }
+    try {
+        const raw = node_fs_1.default.readFileSync(bindingsPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!isObject(parsed)) {
+            return {
+                present: true,
+                malformed: true,
+                data: {},
+                warnings: [bound('existing .platform-bindings.json does not contain a JSON object — left untouched.')],
+            };
+        }
+        return { present: true, malformed: false, data: parsed, warnings: [] };
+    }
+    catch {
+        return {
+            present: true,
+            malformed: true,
+            data: {},
+            warnings: [bound('existing .platform-bindings.json could not be parsed — left untouched.')],
+        };
+    }
+}
+/**
+ * D-08's absent-only merge. `merged` starts as a deep clone of `existing` —
+ * every field the existing file already carries (including the provisional
+ * `modules`/`ci` namespaces the composer never produces) is preserved
+ * untouched. For each field the composer actually composed (the keys of
+ * `candidateProvenance`): if `existing` lacks that key, fill it in from the
+ * candidate; if `existing` already has it, the merged value stays the
+ * existing one (never overwritten) and — when the candidate's value differs
+ * — one drift entry is recorded. A present `(repo, host)` pair can therefore
+ * never be redirected by a package; Phase 33 D-05's threat stays closed by
+ * construction, not by policy.
+ */
+function mergeAbsentOnly(candidate, candidateProvenance, existing) {
+    const merged = deepCloneJsonSafe(existing);
+    const provenance = [];
+    const provenanceByField = {};
+    const drift = [];
+    const managedFields = Object.keys(candidateProvenance);
+    for (const field of managedFields) {
+        const candidateValue = getNested(candidate, field);
+        if (hasNestedOwn(existing, field)) {
+            const existingValue = getNested(existing, field);
+            provenance.push({ field, value: existingValue, source: 'existing-file' });
+            provenanceByField[field] = 'existing-file';
+            if (!valuesEqual(candidateValue, existingValue)) {
+                drift.push({ key: field, profileValue: candidateValue, effectiveValue: existingValue });
+            }
+        }
+        else {
+            setNested(merged, field, candidateValue);
+            const source = candidateProvenance[field];
+            provenance.push({ field, value: candidateValue, source });
+            provenanceByField[field] = source;
+        }
+    }
+    // Provenance-tag (never overwrite) every leaf the existing file carries
+    // that the composer does not manage at all.
+    const managedSet = new Set(managedFields);
+    const existingLeaves = [];
+    walkLeaves(existing, '', 6, existingLeaves);
+    for (const leaf of existingLeaves) {
+        if (managedSet.has(leaf.path))
+            continue;
+        provenance.push({ field: leaf.path, value: leaf.value, source: 'existing-file' });
+        provenanceByField[leaf.path] = 'existing-file';
+    }
+    return { merged, provenance, provenanceByField, drift };
+}
+// ─── composeBindings ──────────────────────────────────────────────────────────
+const ABSENT_PROFILE_META = Object.freeze({
+    resolved: false,
+    packageName: null,
+    version: null,
+    source: 'none',
+    dataPath: null,
+});
+/**
+ * Compose a `.platform-bindings.json` candidate for the project at `cwd`,
+ * validate it, merge it against any existing file, and write only when
+ * `opts.write === true` and the result is composable. Never throws and
+ * never exits non-zero — every failure mode produces a bounded warning and
+ * continues (D-09).
+ */
+function composeBindings(cwd, opts = {}) {
+    const warnings = [];
+    try {
+        const { provider, warnings: providerWarnings } = (0, git_provider_cjs_1.resolveProvider)(cwd);
+        pushDeduped(warnings, providerWarnings);
+        const seedResult = readSeed(cwd, { _globalRoot: opts._globalRoot });
+        pushDeduped(warnings, seedResult.warnings);
+        const candidateResult = composeCandidate(cwd, seedResult.values, provider, opts);
+        pushDeduped(warnings, candidateResult.warnings);
+        const existing = readExistingBindings(cwd);
+        pushDeduped(warnings, existing.warnings);
+        if (existing.malformed) {
+            return {
+                profile: seedResult.profile,
+                provider,
+                seed: seedResult.values,
+                present: existing.present,
+                composable: false,
+                composed: null,
+                provenance: [],
+                drift: [],
+                action: 'none',
+                wrote: false,
+                warnings,
+            };
+        }
+        const mergeResult = mergeAbsentOnly(candidateResult.candidate, candidateResult.provenance, existing.data);
+        const disposeResult = validateAndDispose(mergeResult.merged, mergeResult.provenanceByField);
+        pushDeduped(warnings, disposeResult.warnings);
+        if (!disposeResult.composable || disposeResult.composed === null) {
+            return {
+                profile: seedResult.profile,
+                provider,
+                seed: seedResult.values,
+                present: existing.present,
+                composable: false,
+                composed: null,
+                provenance: mergeResult.provenance,
+                drift: mergeResult.drift,
+                action: 'none',
+                wrote: false,
+                warnings,
+            };
+        }
+        const composed = disposeResult.composed;
+        let action;
+        if (!existing.present) {
+            action = 'create';
+        }
+        else if (hasAnyNewKey(composed, existing.data)) {
+            action = 'update';
+        }
+        else {
+            action = 'unchanged';
+        }
+        let wrote = false;
+        if (opts.write === true && action !== 'unchanged') {
+            const bindingsPath = node_path_1.default.join(cwd, '.platform-bindings.json');
+            (0, shell_command_projection_cjs_1.platformWriteSync)(bindingsPath, JSON.stringify(composed, null, 2) + '\n');
+            wrote = true;
+        }
+        return {
+            profile: seedResult.profile,
+            provider,
+            seed: seedResult.values,
+            present: existing.present,
+            composable: true,
+            composed,
+            provenance: mergeResult.provenance,
+            drift: mergeResult.drift,
+            action,
+            wrote,
+            warnings,
+        };
+    }
+    catch {
+        return {
+            profile: ABSENT_PROFILE_META,
+            provider: git_provider_cjs_1.DEFAULT_PROVIDER,
+            seed: {},
+            present: false,
+            composable: false,
+            composed: null,
+            provenance: [],
+            drift: [],
+            action: 'none',
+            wrote: false,
+            warnings: [...warnings, 'binding composition failed unexpectedly.'],
+        };
+    }
+}
+// ─── cmdComposeBindings ───────────────────────────────────────────────────────
+/**
+ * CLI adapter for `pp-tools query compose-bindings`. Resolves the project
+ * root via `findProjectRoot(cwd) || cwd`, exactly as `cmdPlatformBindings`
+ * does, then calls `composeBindings` and emits the result as data — a
+ * verdict is never a process error.
+ */
+function cmdComposeBindings(cwd, options, raw) {
+    let root;
+    try {
+        root = (0, project_root_cjs_1.findProjectRoot)(cwd) || cwd;
+    }
+    catch {
+        root = cwd;
+    }
+    const result = composeBindings(root, { write: options.write === true, offline: options.offline === true });
+    output(result, raw);
+}