@wildo-ai/saas-models 1.1.5 → 1.1.7

package/dist/esm/systems-of-record/system-of-record-facet.shared.schemas.js

@@ -58,7 +58,10 @@ import '@wildo-ai/zod-decorators';
 import { z } from 'zod';
 import { HttpApiTransportDialect } from '../http-api-binding/http-api-transport-dialect.shared.js';
 import { HttpApiKeyComponentCodec } from '../http-api-binding/http-api-binding.shared.schemas.js';
+import { ExternalDataIncrementalExtractionMode } from '../external-data/external-data-pipeline.shared.schemas.js';
 import { SystemOfRecordCredentialKind } from './system-of-record-credential-kind.shared.js';
+import { SystemOfRecordActionCallShape, SYSTEM_OF_RECORD_ACTION_CALL_SHAPE_DIALECT } from './system-of-record-actions.shared.schemas.js';
+import { SystemOfRecordErrorCode } from './system-of-record-error-codes.shared.js';
 import { SYSTEM_OF_RECORD_ENABLED_SLOT, SYSTEM_OF_RECORD_SLOT_SLUG_PATTERN, deriveSystemOfRecordEnabledEnvVarName } from './system-of-record-env.shared.js';
 /** @wildo_source:part:start saas.models.systems-of-record facet:layer:shared facet:audience:app-developer */
 /**
@@ -376,7 +379,9 @@ export const SystemOfRecordCredentialOfferSchema = z.discriminatedUnion('kind',
 export var SystemOfRecordODataListPaging;
 (function (SystemOfRecordODataListPaging) {
     /**
-     * `$top` + `$skip` — one request for any page, which is what a page-numbered contract wants.
+     * `$top` + `$skip` — one request for any page, which is what a page-numbered contract wants, unless the
+     * service serves fewer rows than `$top` and hands back a continuation: the page is then read to its end
+     * along the continuation (#1998), so the next page's `$skip` does not jump the rows the service held back.
      *
      * The default, because it is what OData v4 defines and what an uncatalogued service serves.
      */
@@ -385,8 +390,12 @@ export var SystemOfRecordODataListPaging;
      * `@odata.nextLink` only: the service hands back a continuation URL and refuses to be addressed by
      * offset.
      *
-     * The consequence is structural rather than a detail — a cursor has no page NUMBER, so page N costs
-     * N requests. The engine walks forward and refuses past a bound rather than pretending otherwise.
+     * The consequence is structural rather than a detail — a cursor has no page NUMBER, so reaching a page
+     * costs one request per page before it. The engine asks for the page size with `Prefer:
+     * odata.maxpagesize` on v4 (v2 has no such preference, so the service's own size decides) — never with
+     * `$top`, which would cap the whole collection (#1991) — walks forward
+     * counting ROWS rather than links (the service may serve a page size of its own, #1998), and refuses
+     * past a bound rather than pretending otherwise.
      */
     SystemOfRecordODataListPaging["NEXT_LINK_ONLY"] = "next-link-only";
 })(SystemOfRecordODataListPaging || (SystemOfRecordODataListPaging = {}));
@@ -453,6 +462,36 @@ export const SystemOfRecordPartitionSupportSchema = z.strictObject({
     codec: z.enum(HttpApiKeyComponentCodec),
     valueShape: z.enum(SystemOfRecordPartitionValueShape),
 });
+/**
+ * A step a vendor requires before it accepts ANY modifying request — a row write or a writing action — beyond the
+ * credential every request carries (#1726).
+ *
+ * Declared by the FACET because it is a fact about the product, and refused at startup by the engine for every step it
+ * does not perform (`WRITE_PREREQUISITE_NOT_SUPPORTED`): a write the vendor is known to refuse must not be opened, since
+ * it would only surface as a remote `403` at the first request, under a code that names nothing.
+ */
+export var SystemOfRecordWritePrerequisite;
+(function (SystemOfRecordWritePrerequisite) {
+    /**
+     * SAP Gateway's cross-site-request-forgery protection: a modifying request must carry an `X-CSRF-Token` obtained by a
+     * prior NON-modifying request sent with `X-CSRF-Token: Fetch`, together with the session cookie that request set.
+     * spec-cite: SAP Help Portal, SAP Gateway Foundation — "Cross-Site Request Forgery Protection"
+     * (https://help.sap.com/saphelp_gateway20sp12/helpdata/en/e6/cae27d5e8d4996add4067280c8714e/frameset.htm).
+     */
+    SystemOfRecordWritePrerequisite["CSRF_TOKEN_HANDSHAKE"] = "csrf-token-handshake";
+})(SystemOfRecordWritePrerequisite || (SystemOfRecordWritePrerequisite = {}));
+/**
+ * The OData v4 control information that carries an entity's ETag in a JSON row (#1726) — the only row version an OData
+ * vendor can declare in `rowVersionField`, and the value the OData write dialect sends as `If-Match`.
+ *
+ * The OData 4.0 spelling. A payload that is not OData-Version 4.0 omits the `odata.` infix (`@etag`); the engine asks
+ * for 4.0 on its OData requests (`OData-MaxVersion: 4.0`), so a conformant service answers this spelling. A field MAPPED
+ * onto the tag, and a `VERSION_CHECKED` comparison, read this spelling only; the write dialect alone also reads the
+ * short form when it derives `If-Match`, which only widens what it can condition on.
+ * spec-cite: OData JSON Format Version 4.01 §4.5.10 (Control Information: etag (odata.etag)) and §4.5 ("In requests and
+ * responses with an OData-Version header with a value of 4.0 control information names are prefixed with @odata.").
+ */
+export const ODATA_ENTITY_TAG_CONTROL_INFORMATION = '@odata.etag';
 /**
  * What a vendor is, as a system of record. Parsed rather than trusted because #1057 lets a PACKAGE
  * ship one — a record produced by one package version and read by another.
@@ -499,7 +538,109 @@ export const SystemOfRecordVendorFacetSchema = z.strictObject({
      * such a facet is refused by name rather than silently doing nothing.
      */
     partition: SystemOfRecordPartitionSupportSchema.optional(),
+    /**
+     * The change-tracking mechanisms this vendor's deployments support, which a pipeline may read
+     * incrementally through (#1682). A pipeline declaring `incremental.mode` outside this list is refused
+     * at startup, naming the vendor.
+     *
+     * A VENDOR property rather than a dialect constant: whether a deployment can say what changed is a
+     * fact about the product (Odoo's ORM stamps `write_date` on every model that logs access; an OData
+     * service may or may not enable change tracking, #1722), not about the wire language.
+     *
+     * ABSENT means none — a real answer: that vendor's pipelines run full passes only.
+     */
+    incrementalExtractionModes: z.array(z.enum(ExternalDataIncrementalExtractionMode)).optional(),
+    /**
+     * The service-defined OData error codes with which this vendor says a tracked change position has EXPIRED (#1722), for a
+     * vendor that answers it with its own code rather than the protocol's `410 Gone` / `404 Not Found`.
+     *
+     * A delta-link pass whose link the vendor no longer honours starts over with a full pass. The protocol names the status
+     * for an expired URL, and the engine recognises it for every vendor; a vendor that answers something else instead
+     * states its code here, so the fallback does not depend on guessing which `400` means "too old". Dataverse documents
+     * `0x80044352` (`ExpiredVersionStamp`, "Please perform a full sync").
+     *
+     * ABSENT means the vendor answers the protocol's status, or has no change tracking.
+     */
+    odataExpiredChangePositionErrorCodes: z.array(z.string().min(1)).optional(),
+    /**
+     * The ACTION call shapes this vendor's product supports (#1678) — how a declared action is called on it: Odoo's
+     * `execute_kw` on a model method, an OData bound action, an OData unbound action import.
+     *
+     * A VENDOR property, like `partition`: whether a product exposes callable operations beyond row reads is a fact about
+     * the product, and a generic OData service may expose none. A binding declaring an action whose shape its vendor does
+     * not list is refused at boot, naming the vendor. ABSENT means none — the vendor is read (and perhaps written) only.
+     * Each listed shape must be spoken over one of the facet's own `dialects`.
+     */
+    actionCallShapes: z.array(z.enum(SystemOfRecordActionCallShape)).optional(),
+    /**
+     * The remote field this vendor's product maintains on EVERY row as its version — changed by the product itself on every
+     * write, never by a caller (#1724, #1726). Odoo: `write_date`, the ORM's "Last Updated on". An OData v4 vendor that
+     * serves entity tags: {@link ODATA_ENTITY_TAG_CONTROL_INFORMATION} (`@odata.etag`), and nothing else.
+     *
+     * A binding may declare `writeConcurrency: VERSION_CHECKED` only against a vendor that names one, and only with a
+     * version field that maps onto it (refused at boot, `WRITE_ROW_VERSION_NOT_SUPPORTED_BY_VENDOR`). The engine then
+     * compares the version a caller read with the one it reads just before the write.
+     *
+     * ## What that comparison is worth depends on the DIALECT, not on this field
+     *
+     * - **Odoo (best-effort).** Its external API has no conditional write — `write(ids, vals)` applies the values, with no
+     *   precondition — so the comparison and the write are two separate calls, and a change landing between them is
+     *   overwritten. The check NARROWS the lost-update window to the gap between two calls; it does not close it.
+     * - **OData v4 (atomic).** The OData write dialect sends the version as `If-Match` on the `PATCH` or `DELETE`, and the
+     *   service itself refuses a mismatch with `412 Precondition Failed` and applies nothing. The engine's comparison
+     *   before sending is then only a fast refusal; the guarantee is the vendor's.
+     *   spec-cite: OData Version 4.01 Part 1: Protocol §8.2.4 (Header If-Match) — "the service MUST respond with 412
+     *   Precondition Failed and MUST ensure that no observable change occurs as a result of the request".
+     *
+     * Declaring it for an OData vendor is also what lets its writes send the row's own entity tag rather than `*`: the
+     * write dialect reads `@odata.etag` from the row it reads first, so a row moved (into another partition, say) between
+     * that read and the write is refused by the vendor instead of written.
+     *
+     * A VENDOR property, like `incrementalExtractionModes`: whether a product maintains a per-row version is a fact about the
+     * product. ABSENT means none, and a binding against such a vendor states `LAST_WRITER_WINS` instead.
+     */
+    rowVersionField: z.string().min(1).max(120).optional(),
+    /**
+     * What this vendor requires before any modifying request (#1726) — see {@link SystemOfRecordWritePrerequisite}. ABSENT
+     * means nothing beyond the credential. A binding opening writes against a vendor listing a step the engine does not
+     * perform is refused at startup.
+     */
+    writePrerequisites: z.array(z.enum(SystemOfRecordWritePrerequisite)).optional(),
 }).superRefine((facet, context) => {
+    /*
+     * #1726 — over OData the row version IS the entity tag: it is what `If-Match` carries and what the service compares.
+     * A property value (a `modifiedon` column, a `RowVersion` field) is not an ETag, and sending one as `If-Match` would
+     * be refused as a mismatch on every write — so an OData vendor names the entity tag or nothing.
+     */
+    if (facet.rowVersionField !== undefined && facet.dialects.includes(HttpApiTransportDialect.ODATA)
+        && facet.rowVersionField !== ODATA_ENTITY_TAG_CONTROL_INFORMATION) {
+        context.addIssue({
+            code: 'custom',
+            path: ['rowVersionField'],
+            message: `An OData vendor's row version is its entity tag, "${ODATA_ENTITY_TAG_CONTROL_INFORMATION}" — got "${facet.rowVersionField}".`,
+        });
+    }
+    // #1678 — a call shape is spoken over one dialect; listing a shape over a dialect the vendor is not read through would
+    // advertise an action no instance of it could ever reach.
+    for (const [index, shape] of (facet.actionCallShapes ?? []).entries()) {
+        if (!facet.dialects.includes(SYSTEM_OF_RECORD_ACTION_CALL_SHAPE_DIALECT[shape])) {
+            context.addIssue({
+                code: 'custom',
+                path: ['actionCallShapes', index],
+                message: `Action call shape "${shape}" is spoken over ${SYSTEM_OF_RECORD_ACTION_CALL_SHAPE_DIALECT[shape]}, which this vendor's dialects do not list.`,
+            });
+        }
+    }
+    // #1722 — an expired-position code is read only by a delta-link pass, so a vendor listing one without that mode states a
+    // fact nothing could ever consult.
+    if (facet.odataExpiredChangePositionErrorCodes !== undefined
+        && !(facet.incrementalExtractionModes ?? []).includes(ExternalDataIncrementalExtractionMode.ODATA_DELTA_LINK)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['odataExpiredChangePositionErrorCodes'],
+            message: `An expired change-position code is read only by the "${ExternalDataIncrementalExtractionMode.ODATA_DELTA_LINK}" mode, which this vendor's incrementalExtractionModes do not list.`,
+        });
+    }
     const seenDialects = new Set();
     for (const [index, dialect] of facet.dialects.entries()) {
         if (seenDialects.has(dialect)) {
@@ -532,7 +673,214 @@ export const SystemOfRecordVendorFacetSchema = z.strictObject({
         }
     }
 });
+/**
+ * The export a package's `./systems-of-record` module presents: a record of facets keyed by vendor id. The
+ * backend's facet resolver and `wildo secrets` (which lists the credential slots an instance needs) both read
+ * a facet module through this name, so it is declared once, beside the shape it carries.
+ */
+export const SYSTEM_OF_RECORD_FACET_RECORD_EXPORT = 'PROVIDER_CATALOGUE_SYSTEM_OF_RECORD_FACETS';
+/** The subpath a package exports its facet module under: `<package>/systems-of-record`. */
+export const SYSTEM_OF_RECORD_FACET_MODULE_SUBPATH = '/systems-of-record';
 /** @wildo_source:part:end saas.models.systems-of-record */
+/**
+ * The specifier of `packageName`'s facet module. ONE spelling for the backend's resolver, `wildo secrets` and the
+ * discovery that records the modules, so the three cannot disagree about where a package's facets live (#1675).
+ */
+export function systemOfRecordFacetModuleSpecifier(packageName) {
+    return `${packageName}${SYSTEM_OF_RECORD_FACET_MODULE_SUBPATH}`;
+}
+/** The package a facet module specifier belongs to: `@acme/erp/systems-of-record` → `@acme/erp`. */
+export function packageOfSystemOfRecordFacetModule(specifier) {
+    return specifier.endsWith(SYSTEM_OF_RECORD_FACET_MODULE_SUBPATH) ? specifier.slice(0, -SYSTEM_OF_RECORD_FACET_MODULE_SUBPATH.length) : specifier;
+}
+/**
+ * The ONE base facet for a vendor, or a refusal naming both sources when two present one (#1675).
+ *
+ * Refused rather than "the first in authority order wins": a base facet carries the vendor's partition, and module
+ * order is the sorted order of discovered package names, so which package's partition confined a tenant's rows would
+ * otherwise depend on how two names sort — and a newly installed package could replace the library's facet with
+ * no opt-in at all. A package that knows more about a vendor it does not own ADDS to the base through an augmentation
+ * an instance opts into; it never presents a second base.
+ *
+ * `undefined` when no source presents the vendor — the caller's own refusal names the vendor.
+ *
+ * assurance-control: WILDO.DATA.TENANT_ISOLATION WILDO.SECURITY.FAIL_CLOSED — two base facets for one vendor refuse,
+ * so a tenant-confinement declaration never comes from whichever of two packages sorts first.
+ */
+export function selectSystemOfRecordBaseFacet(input) {
+    const [first, second] = input.candidates;
+    if (first === undefined)
+        return undefined;
+    if (second !== undefined) {
+        return {
+            conflict: `Vendor '${input.vendor}' has two base facets: from ${first.source} and from ${second.source}. One source owns a `
+                + 'vendor\'s facet; a package that adds to it ships an augmentation (`PROVIDER_CATALOGUE_SYSTEM_OF_RECORD_FACET_AUGMENTATIONS`) '
+                + 'an instance opts into. Uninstall one of the two, or have it ship an augmentation instead.',
+            detail: { vendor: input.vendor, sources: input.candidates.map((candidate) => candidate.source) },
+        };
+    }
+    return { facet: SystemOfRecordVendorFacetSchema.parse(first.raw), source: first.source };
+}
+/** @wildo_source:part:start saas.models.systems-of-record.facet-augmentation facet:kind:api facet:audience:app-developer */
+/**
+ * What a package ADDS to a vendor facet it does not own (#1675) — the facet counterpart of a provider
+ * augmentation (#1672), with its own code path.
+ *
+ * One base facet per vendor answers — the one package module that presents it; two refuse, naming both. An
+ * augmentation adds to it: a PARTITION declaration for a vendor whose base declares none (say a `company_id`
+ * FIELD every row of an ERP carries, shipped by a package that knows the vendor better), or further
+ * CREDENTIAL OFFERS. It never replaces or removes anything the base declares — two declarations of one
+ * partition, or one credential kind offered twice, refuse at startup naming both sources.
+ *
+ * Only a FIELD partition can be confined. A PATH-SEGMENT partition (a company chosen in the request path) is
+ * refused when an instance sets `partition: true`, augmented or not, because nothing narrows a read the path
+ * already scoped — so augmenting one declares something no instance can use.
+ *
+ * INERT until an instance opts in: `systemsOfRecord.<name>.facetAugmentations` names the PACKAGES whose
+ * augmentation applies to that instance. The facet is the single partition authority, so a partition
+ * arriving from a package is a tenant-confinement change and is never applied because a package happens
+ * to be installed.
+ *
+ * A package presents its augmentations beside its facets, from its `./systems-of-record` export, as a
+ * record keyed by vendor id under {@link SYSTEM_OF_RECORD_FACET_AUGMENTATION_RECORD_EXPORT}. A package
+ * may ship augmentations and no facet at all. Its module is found the way every facet module is: by the
+ * provider discovery walk `wildo config sync` runs, which reads the framework's names, the application's own
+ * scope, and any package the application lists in `providers.packages` (#1676). Listing ADMITS the package;
+ * an instance's opt-in ACTIVATES its augmentation. A package the walk did not record is refused by name.
+ *
+ * Entity descriptions are not augmentable: the facet declares none today, so there is nothing to add to.
+ */
+export const SystemOfRecordVendorFacetAugmentationSchema = z.strictObject({
+    /** The vendor this augments — must equal the key it is recorded under. */
+    vendor: z.string().regex(/^[a-z][a-z0-9-]*$/, 'A vendor id is lower-kebab-case.').max(40),
+    /** A partition declaration for a vendor whose base facet declares none. */
+    partition: SystemOfRecordPartitionSupportSchema.optional(),
+    /** Credential kinds the base facet does not offer, each with this vendor's policy for it. */
+    credentialOffers: z.array(SystemOfRecordCredentialOfferSchema).min(1).optional(),
+}).superRefine((augmentation, context) => {
+    if (augmentation.partition === undefined && augmentation.credentialOffers === undefined) {
+        context.addIssue({ code: 'custom', path: [], message: 'A facet augmentation that adds nothing is refused: declare a partition, credential offers, or both.' });
+    }
+    const seenKinds = new Set();
+    for (const [index, offer] of (augmentation.credentialOffers ?? []).entries()) {
+        if (seenKinds.has(offer.kind)) {
+            context.addIssue({ code: 'custom', path: ['credentialOffers', index], message: `Duplicate credentialOffers member "${offer.kind}".` });
+        }
+        seenKinds.add(offer.kind);
+    }
+});
+/** The export a package's `./systems-of-record` module presents its facet augmentations under: a record keyed by vendor id. */
+export const SYSTEM_OF_RECORD_FACET_AUGMENTATION_RECORD_EXPORT = 'PROVIDER_CATALOGUE_SYSTEM_OF_RECORD_FACET_AUGMENTATIONS';
+/** Why an instance's opted-in augmentations cannot be applied. */
+export var SystemOfRecordFacetAugmentationRefusalKind;
+(function (SystemOfRecordFacetAugmentationRefusalKind) {
+    /** A package the instance opted in ships no augmentation for its vendor. */
+    SystemOfRecordFacetAugmentationRefusalKind["NOT_FOUND"] = "not-found";
+    /** Two sources declare the same partition or credential kind. */
+    SystemOfRecordFacetAugmentationRefusalKind["CONFLICT"] = "conflict";
+    /** An augmentation, or the facet it produces once merged, fails the facet schema. */
+    SystemOfRecordFacetAugmentationRefusalKind["INVALID"] = "invalid";
+})(SystemOfRecordFacetAugmentationRefusalKind || (SystemOfRecordFacetAugmentationRefusalKind = {}));
+/**
+ * Folds an instance's opted-in augmentations into its base facet — and refuses, naming both sources, the moment two
+ * of them declare the same thing. ONE implementation for the backend's facet resolver and `wildo secrets`, so a
+ * listing cannot ask for a credential the backend would refuse, or miss one an augmentation offers.
+ *
+ * `augmentations` is in the instance's declared opt-in order; each `raw` is what the package's module presents under
+ * {@link SYSTEM_OF_RECORD_FACET_AUGMENTATION_RECORD_EXPORT} for this vendor (`undefined` when it presents none),
+ * parsed here like a facet because it was produced by one package version and is read by another.
+ *
+ * assurance-control: WILDO.DATA.TENANT_ISOLATION WILDO.SECURITY.FAIL_CLOSED — a partition declaration (how a tenant's
+ * rows are confined) is admitted from a package only when the instance opted that package in, only for a vendor whose
+ * base facet declares none, never twice, and every admitted one is recorded with the package that contributed it.
+ */
+export function applySystemOfRecordFacetAugmentations(input) {
+    const { vendor, base } = input;
+    let partition = base.facet.partition;
+    let partitionSource = partition === undefined ? undefined : base.source;
+    let augmentedPartitionPackage;
+    const credentialOffers = [...base.facet.credentialOffers];
+    const offerSources = new Map(base.facet.credentialOffers.map((offer) => [offer.kind, base.source]));
+    const augmentedKinds = {};
+    for (const { packageName, raw, unreadable } of input.augmentations) {
+        if (raw === undefined) {
+            return {
+                refusal: SystemOfRecordFacetAugmentationRefusalKind.NOT_FOUND,
+                message: unreadable === undefined
+                    ? `Package ${packageName} is opted in to augment vendor '${vendor}' and ships no augmentation for it — its `
+                        + '`./systems-of-record` module augments other vendors only.'
+                    : `Package ${packageName} is opted in to augment vendor '${vendor}', and its facet module `
+                        + `${systemOfRecordFacetModuleSpecifier(packageName)} could not be read: ${unreadable}.`,
+                detail: { vendor, packageName, ...(unreadable === undefined ? {} : { unreadable }) },
+            };
+        }
+        const parsed = SystemOfRecordVendorFacetAugmentationSchema.safeParse(raw);
+        if (!parsed.success) {
+            return {
+                refusal: SystemOfRecordFacetAugmentationRefusalKind.INVALID,
+                message: `Package ${packageName}'s augmentation of vendor '${vendor}' is malformed: ${z.prettifyError(parsed.error)}`,
+                detail: { vendor, packageName },
+            };
+        }
+        const augmentation = parsed.data;
+        if (augmentation.vendor !== vendor) {
+            return {
+                refusal: SystemOfRecordFacetAugmentationRefusalKind.NOT_FOUND,
+                message: `Package ${packageName} records an augmentation under vendor '${vendor}' that declares vendor '${augmentation.vendor}'.`,
+                detail: { vendor, packageName, declaredVendor: augmentation.vendor },
+            };
+        }
+        const source = `package ${packageName}`;
+        if (augmentation.partition !== undefined) {
+            if (partitionSource !== undefined) {
+                return {
+                    refusal: SystemOfRecordFacetAugmentationRefusalKind.CONFLICT,
+                    message: `Vendor '${vendor}' would be partitioned twice: by ${partitionSource} and by ${source}. The facet is the one `
+                        + 'authority on how rows are confined — remove one of the two.',
+                    detail: { vendor, sources: [partitionSource, source] },
+                };
+            }
+            partition = augmentation.partition;
+            partitionSource = source;
+            augmentedPartitionPackage = packageName;
+        }
+        for (const offer of augmentation.credentialOffers ?? []) {
+            const existing = offerSources.get(offer.kind);
+            if (existing !== undefined) {
+                return {
+                    refusal: SystemOfRecordFacetAugmentationRefusalKind.CONFLICT,
+                    message: `Vendor '${vendor}' would offer credential kind '${offer.kind}' twice: from ${existing} and from ${source}.`,
+                    detail: { vendor, credentialKind: offer.kind, sources: [existing, source] },
+                };
+            }
+            offerSources.set(offer.kind, source);
+            credentialOffers.push(offer);
+            augmentedKinds[offer.kind] = packageName;
+        }
+    }
+    // Re-parsed as a whole, so every rule the base schema holds (a kind's slots against the vendor's) holds for the
+    // merged facet too.
+    const merged = SystemOfRecordVendorFacetSchema.safeParse({
+        ...base.facet,
+        credentialOffers,
+        ...(partition === undefined ? {} : { partition }),
+    });
+    if (!merged.success) {
+        const packages = input.augmentations.map((augmentation) => augmentation.packageName);
+        return {
+            refusal: SystemOfRecordFacetAugmentationRefusalKind.INVALID,
+            message: `Vendor '${vendor}''s facet, augmented by ${packages.join(', ')}, is no longer a valid facet: ${z.prettifyError(merged.error)}`,
+            detail: { vendor, packages },
+        };
+    }
+    return {
+        facet: merged.data,
+        augmentedBy: {
+            ...(augmentedPartitionPackage === undefined ? {} : { partition: augmentedPartitionPackage }),
+            credentialKinds: augmentedKinds,
+        },
+    };
+}
 /**
  * How this vendor pages an OData collection read — the ONE place an absent declaration becomes an
  * answer (#1292).
@@ -554,6 +902,24 @@ export function resolveSystemOfRecordODataListPaging(facet) {
 export function findSystemOfRecordCredentialOffer(facet, credentialKind) {
     return facet.credentialOffers.find((offer) => offer.kind === credentialKind);
 }
+/**
+ * Which credential kind an instance uses — decided ONCE, for the backend registry that enforces it at boot
+ * and for `wildo secrets`, which lists the secret slots that kind needs (#1637). Two readers deriving it
+ * separately is how a listing comes to ask for a secret the backend will not read.
+ *
+ * DECLARED when the instance names one the facet offers; DERIVED when the instance names none and the
+ * facet offers exactly one, because an author asked to choose between one option is being asked a question
+ * the mechanism already holds the answer to (`derive-before-you-ask.md`). Otherwise a refusal, carrying
+ * what the facet does offer so the reader can name it: a kind the vendor does not offer, or several on
+ * offer and none chosen — the day the author acquires a real decision.
+ */
+export function chooseSystemOfRecordCredentialKind(declaredKind, facet) {
+    const offered = facet.credentialOffers.map((offer) => offer.kind);
+    if (declaredKind !== undefined) {
+        return offered.includes(declaredKind) ? { kind: declaredKind } : { refusal: SystemOfRecordErrorCode.CREDENTIAL_KIND_NOT_OFFERED, offered };
+    }
+    return offered.length === 1 ? { kind: offered[0] } : { refusal: SystemOfRecordErrorCode.CREDENTIAL_KIND_AMBIGUOUS, offered };
+}
 /**
  * The ONE place the vendor's slots and the credential kind's slots are joined.
  *