@bsv/dpp-profiles 0.3.0-beta.1

package/LICENSE

@@ -0,0 +1,58 @@
+Open BSV License Version 6 – granted by BSV Association, Alpenstrasse 15, 6300
+Zug, Switzerland (CHE-427.008.338) ("Licensor"), to you as a user (henceforth
+"You", "User" or "Licensee").
+
+For the purposes of this license, the definitions below have the following
+meanings:
+
+"Bitcoin Protocol" means the protocol implementation, cryptographic rules,
+network protocols, and consensus mechanisms in the Bitcoin White Paper as
+described here https://protocol.bsvblockchain.org.
+
+"Bitcoin White Paper" means the paper entitled 'Bitcoin: A Peer-to-Peer
+Electronic Cash System' published by 'Satoshi Nakamoto' in October 2008.
+
+"BSV Blockchain" means:
+
+  (a) the Bitcoin blockchain containing block height #556767 with the hash
+      "000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b" and
+      that contains the longest honest persistent chain of blocks which has been
+      produced in a manner which is consistent with the rules set forth in the
+      Network Access Rules; and
+  (b) the test blockchains that contain the longest honest persistent chains of
+      blocks which has been produced in a manner which is consistent with the
+      rules set forth in the Network Access Rules.
+
+"Network Access Rules" or "Rules" means the set of rules regulating the
+relationship between BSV Association and the nodes on BSV based on the Bitcoin
+Protocol rules and those set out in the Bitcoin White Paper, and available here
+https://bsvblockchain.org/network-access-rules.
+
+"Software" means the software the subject of this license, including any/all
+intellectual property rights therein and associated documentation files.
+
+BSV Association grants permission, free of charge and on a non-exclusive basis
+to any person obtaining a copy of the Software to deal in the Software, including
+without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to and conditioned upon the following
+conditions:
+
+1 - The text "© BSV Association", and this license shall be included in all
+copies or substantial portions of the Software.
+
+2 - The Software, and any software that is derived from the Software or parts
+thereof, may only be used exclusively on the BSV Blockchain.
+
+For the avoidance of doubt, this license is granted subject to and conditioned
+upon your compliance with these terms only and is limited to uses on the BSV
+Blockchain. Any exercise of rights not compliant with these terms including
+use not for the BSV Blockchain is deemed outside the scope of the license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES REGARDING ENTITLEMENT,
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS THEREOF BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @bsv/dpp-profiles
+
+**Experimental prerelease:** For implementation and interoperability testing. APIs may change significantly before a stable release. Pin exact package versions and retain your lockfile. This package is not declared production-ready. Package versions are separate from the specification, wire-format and frozen profile versions they implement.
+
+## Install
+
+This is a pre-1.0 candidate. After publication, install the selected version from npm:
+
+```sh
+npm install --save-exact @bsv/dpp-profiles@0.3.0-beta.1
+```
+
+The runtime requires Node >=22 and ECMAScript modules. The JSON data exports can be read in other runtimes. No repository checkout or package build is needed after installation.
+
+The canonical industry data profiles of the DPP standard, as `spec/profiles.md` defines them: immutable manifests, the artefacts generated from them, the digests they are frozen at, and the GS1 identifier helpers a writer uses to mint an identifier it can stand behind. Data first: the manifests, schemas and generated documents are plain files any language reads, and the one runtime dependency of the code beside them is the RFC 8785 canonicaliser (`canonicalize`) the projection digest uses. The code reads its data files through the Node file system, so the root entry point is a Node module; a browser or another language reads the data files directly through the `./manifests/*`, `./schemas/*`, `./generated/*` and `./frozen.json` entry points.
+
+## What is in it
+
+| Path | What it is |
+|---|---|
+| `manifests/<id>@<version>.json` | The canonical definition of one profile: every field with its pointer, semantic URI, value type, unit or code list, resolved constraints, cardinality, granularity, provenance, access tier, obligation, legal basis and applicability; the stamps, event mappings, access tiers, sources and identity model. Immutable once published. |
+| `schemas/profile-manifest.schema.json` | The JSON Schema (2020-12) every manifest validates against. |
+| `schemas/product-identity.schema.json` | The model, batch and item identity document a passport may relate. |
+| `generated/payload-schema/<profile>.public.schema.json` | The JSON Schema for the public payload carried on chain, generated from the manifest. |
+| `generated/payload-schema/<profile>.restricted.schema.json` | The same for the off-chain restricted tiers. |
+| `generated/consumer/<id>-v<version>.json` | The legacy consumer document the registry serves and the application publishes, generated from the manifest. |
+| `generated/mapping/<profile>.md` | The row-level field mapping inventory of each current profile, generated from the manifest; `needs review` where no generator can decide. |
+| `generated/index.json` | Every file with its digest. |
+| `frozen.json` | The digests every published manifest and generated file is held to. |
+| `src/identifiers.ts` | GS1 check digit, GTIN-14 spelling, the demonstration prefix 952 and the Digital Link path parser and builder. |
+| `src/combinations.ts` | `checkSelection`: supported combinations of baseline, industry, exchange and operator profiles pass, and contradictory selections are refused by name (a write under a superseded version, a claim on a proposed profile, a single operator with peers, a federation of one). |
+| `src/mapping.ts` | `mapNativeOperation`: the conditional lifecycle mapping of `spec/rules.md` §2, one of four outcomes with a loss list on every outcome that is not lossless. |
+| `src/gs1-resolution.ts`, `src/gs1-epc-binary.ts` | The `gs1-digital-link@1` discovery profile (`spec/gs1-discovery.md`): the full grammar for primary key 01 with its qualifiers and data attributes, key-tuple equivalence across hosts, EPC-binary decompression for SGTIN-96 and SGTIN-198, resolution records, the linkset hierarchy and selection, and the resolver description file; `schemas/gs1/` carries the pinned GS1 resolver schemas. |
+| `manifests/interoperability/*.json`, `schemas/interoperability-profile.schema.json` | The interoperability profiles: discovery (`gs1-digital-link@1`), source exchange (`epcis-json@1`) and mapping (`epcis-vsc@1`), each recording its standards, pinned artefacts, formats, limits and what it cannot map. |
+| `src/evidence-shapes.ts`, `src/applicability.ts`, `src/projections.ts` | The shared evidence, measurement, certification, document and language shapes of `contracts/profile-evidence.schema.json`, the declarative applicability evaluator of manifest version 2 (`schemas/profile-manifest-v2.schema.json`) whose `unresolved` outcome is never a pass, and `projectPassport`, the pure deterministic `passport-projection@1` of `spec/passport-projections.md` over versioned model, batch and item sources, digested under RFC 8785. |
+
+Five profiles are published: `battery@2`, `textile@2` and `general@2` (current) and `textile@1` and `general@1` (superseded, and served for as long as any state declares them). They were inventoried from the application's attribute registries in full, including the fields captured over life or derived rather than at registration, and frozen. `battery@3` and `textile@3` are draft successors under manifest version 2: opt-in by explicit version, carrying a requirement status per field and a migration outcome per field, and leaving every byte of the two current versions unchanged until a reviewed cutover.
+
+## Working on it
+
+```
+npm run build      # tsc, then the generator: regenerates generated/ and refuses drift from frozen.json
+npm run generate   # the generator alone
+npm run refreeze   # writes the current digests into the manifests and frozen.json; review that diff
+npm test           # schema validity, uniqueness, freezing, deterministic generation, payload validation, identifiers, lifecycle mapping
+```
+
+A frozen profile changes only by publishing a new version. A corrected mandatory field, a changed meaning or an incompatible validation rule is a new version; a state decodes under the version it declares and is never reinterpreted under a newer one. `--refreeze` exists for a reviewed change to the generator's output for an existing version, and the diff it produces is the review.
+
+## Using it
+
+```ts
+import { readManifest, fieldsFor, missingRequired, parseGs1DigitalLink, parseGs1DigitalLinkUri, decompressGs1DigitalLink, projectPassport } from '@bsv/dpp-profiles'
+
+const battery = readManifest('battery@2')
+const { applies, needsReview } = fieldsFor(battery, 'ev')
+const gaps = missingRequired(battery, payload, 'ev') // gaps.missing blocks; gaps.needsReview is shown, never assumed
+const link = parseGs1DigitalLink(passportId)         // link.checkDigitValid, link.demonstration, never allocation authority
+const request = parseGs1DigitalLinkUri(uri)          // key 01 with 22, 10 and 21, data attributes, linkType; never an exception
+const plain = decompressGs1DigitalLink(compressed)   // eh and ex forms carrying SGTIN-96 or SGTIN-198; other schemes refused by name
+const { projection } = projectPassport(input)        // one digest for one set of pinned sources, policy, cutoff and disclosure
+```
+
+A consumer validates a public payload against the generated schema with a validator that asserts formats and refuses an unknown dialect, and reads `needs-review` as a list to show a person, never as satisfied and never as universally required. Syntax and a correct check digit never prove that GS1 allocated a number to the brand a record describes.

package/dist/applicability.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The declarative applicability evaluator (`spec/profiles.md` §3,
+ * `spec/passport-projections.md` §6). A rule is data, never an expression:
+ * category membership, jurisdiction, an effective interval, a numeric
+ * threshold on a payload value, `all` and `any` over those, `needs-review`
+ * for what only a person can decide, and `unresolved` for what the primary
+ * source could not establish. Three outcomes and never a fourth: a field
+ * applies, does not apply, or is unresolved. Unresolved is not satisfied and
+ * is not a failure either; it is shown, and it never becomes a pass.
+ */
+import type { ApplicabilityRule, ProfileManifest } from './index.js';
+import { type AnyProfileField, type AnyProfileManifest, type ApplicabilityRuleV2 } from './manifest-v2.js';
+export type ApplicabilityOutcome = 'applies' | 'not-applicable' | 'unresolved';
+export interface ApplicabilityContext {
+    /** The product category, as the manifest's `applicability.categoryKey` payload value names it. */
+    category?: string;
+    /** The jurisdiction the passport is evaluated for, for example `EU`. */
+    jurisdiction?: string;
+    /** The date or instant the evaluation is made at, for `effective` rules. */
+    asOf?: string;
+    /** Payload values a `threshold` rule may read, as numbers or as `{ value, unit }`. */
+    values?: Record<string, unknown>;
+    /**
+     * The field keys the record declares inapplicable under `inapplicableFields`
+     * (`spec/profiles.md` §3): a declaration by the declaring party, with a
+     * reason, that a conditional data point does not apply to this record. It
+     * turns an unresolved field into not-applicable with the reason `declared`;
+     * it never makes a required, enacted, unconditionally applicable field
+     * optional, because a declaration is not a value.
+     */
+    declaredNotApplicable?: string[];
+}
+export interface ApplicabilityResult {
+    outcome: ApplicabilityOutcome;
+    reasons: string[];
+}
+export declare function evaluateApplicability(rule: ApplicabilityRule | ApplicabilityRuleV2, ctx?: ApplicabilityContext): ApplicabilityResult;
+/** The key under which a record declares fields inapplicable, and the shape of each declaration. */
+export declare const INAPPLICABLE_FIELDS_KEY = "inapplicableFields";
+export interface InapplicabilityDeclaration {
+    field: string;
+    reason: string;
+    declaredBy?: string;
+}
+/** The declarations a payload carries under `inapplicableFields`, as field keys; malformed entries are ignored, never read as a declaration. */
+export declare function declaredInapplicable(payload: Record<string, unknown> | undefined): string[];
+/**
+ * A field's applicability under a context: a declaration under
+ * `inapplicableFields` answers not-applicable with the reason `declared`
+ * only where the rule would otherwise be unresolved or conditional, so a
+ * declaration cannot switch off a field that applies unconditionally; the
+ * rule answers otherwise.
+ */
+export declare function evaluateFieldApplicability(field: Pick<AnyProfileField, 'key' | 'applicability'>, ctx?: ApplicabilityContext): ApplicabilityResult;
+export interface FieldsForResult<F extends AnyProfileField> {
+    applies: F[];
+    notApplicable: F[];
+    unresolved: Array<{
+        field: F;
+        reasons: string[];
+    }>;
+}
+/**
+ * The fields of a version 1 or version 2 manifest under a context: what
+ * applies, what does not, and what is unresolved with its reasons. The
+ * version 1 `fieldsFor` remains the reader for version 1 manifests with a
+ * bare category; this one takes the whole context.
+ */
+export declare function fieldsForV2<M extends AnyProfileManifest>(manifest: M, ctx?: ApplicabilityContext): FieldsForResult<M['fields'][number]>;
+export interface MissingRequiredV2Result<F extends AnyProfileField> {
+    /** Required, applicable, captured at registration, and absent: this blocks. */
+    missing: F[];
+    /** Required and absent, but whether it applies is unresolved: shown, never blocking, never satisfied. */
+    unresolved: Array<{
+        field: F;
+        reasons: string[];
+    }>;
+    /** Required in the profile's own terms but whose requirement status defers it: anticipated, not to be displayed, or under review. Never counted as missing. */
+    deferred: Array<{
+        field: F;
+        status: string;
+    }>;
+}
+/**
+ * Which required fields a payload lacks under a context, on three separate
+ * lists. A field whose applicability is unresolved is never missing and never
+ * satisfied; a field whose requirement status is anticipated, not to be
+ * displayed or under review is deferred and never blocks, so an adopter can
+ * keep incomplete draft data without a false failure or a false pass. A
+ * field the payload declares inapplicable under `inapplicableFields` is
+ * not-applicable where it would otherwise be unresolved.
+ */
+export declare function missingRequiredV2<M extends AnyProfileManifest>(manifest: M, payload: Record<string, unknown>, ctx?: ApplicabilityContext): MissingRequiredV2Result<M['fields'][number]>;
+/** The category value a payload names for a manifest, read at the manifest's declared category key. */
+export declare function categoryOf(manifest: Pick<ProfileManifest, 'applicability'>, payload: Record<string, unknown> | undefined): string | undefined;
+//# sourceMappingURL=applicability.d.ts.map

package/dist/applicability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applicability.d.ts","sourceRoot":"","sources":["../src/applicability.ts"],"names":[],"mappings":"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"}

package/dist/applicability.js

@@ -0,0 +1,181 @@
+import { isFieldV2 } from './manifest-v2.js';
+const applies = (reasons = []) => ({ outcome: 'applies', reasons });
+const notApplicable = (reason) => ({ outcome: 'not-applicable', reasons: [reason] });
+const unresolved = (reason) => ({ outcome: 'unresolved', reasons: [reason] });
+/** The calendar day of a date or instant, as `YYYY-MM-DD`, for a lexicographic comparison that needs no clock. */
+function dayOf(value) {
+    const day = value.slice(0, 10);
+    return /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : /^\d{4}-\d{2}$/.test(value) ? `${value}-01` : /^\d{4}$/.test(value) ? `${value}-01-01` : undefined;
+}
+function thresholdValue(raw, unit) {
+    if (raw == null)
+        return { reason: 'not supplied' };
+    if (typeof raw === 'number')
+        return Number.isFinite(raw) ? { value: raw } : { reason: 'not a finite number' };
+    if (typeof raw === 'object' && !Array.isArray(raw)) {
+        const record = raw;
+        if (typeof record.value !== 'number' || !Number.isFinite(record.value))
+            return { reason: 'carries no finite numeric value' };
+        if (unit != null && record.unit !== unit)
+            return { reason: `is in ${String(record.unit)}, not the rule's ${unit}` };
+        return { value: record.value };
+    }
+    return { reason: 'is not numeric' };
+}
+export function evaluateApplicability(rule, ctx = {}) {
+    switch (rule.rule) {
+        case 'always':
+            return applies();
+        case 'category-in': {
+            const categories = rule.categories ?? [];
+            if (ctx.category == null)
+                return applies(['no category supplied; a category-in rule is read as applying, as fieldsFor reads it']);
+            return categories.includes(ctx.category) ? applies() : notApplicable(`category ${ctx.category} is not one of ${categories.join(', ')}`);
+        }
+        case 'needs-review': {
+            const categories = rule.categories;
+            if (categories != null && ctx.category != null && !categories.includes(ctx.category))
+                return notApplicable(`category ${ctx.category} is outside the categories the review concerns`);
+            return unresolved(`needs review: ${rule.condition ?? 'the condition is not stated'}`);
+        }
+        case 'all': {
+            const results = rule.rules.map((r) => evaluateApplicability(r, ctx));
+            const no = results.filter((r) => r.outcome === 'not-applicable');
+            if (no.length > 0)
+                return { outcome: 'not-applicable', reasons: no.flatMap((r) => r.reasons) };
+            const open = results.filter((r) => r.outcome === 'unresolved');
+            if (open.length > 0)
+                return { outcome: 'unresolved', reasons: open.flatMap((r) => r.reasons) };
+            return applies(results.flatMap((r) => r.reasons));
+        }
+        case 'any': {
+            const results = rule.rules.map((r) => evaluateApplicability(r, ctx));
+            const yes = results.find((r) => r.outcome === 'applies');
+            if (yes != null)
+                return applies(yes.reasons);
+            const open = results.filter((r) => r.outcome === 'unresolved');
+            if (open.length > 0)
+                return { outcome: 'unresolved', reasons: open.flatMap((r) => r.reasons) };
+            return { outcome: 'not-applicable', reasons: results.flatMap((r) => r.reasons) };
+        }
+        case 'jurisdiction-in':
+            if (ctx.jurisdiction == null)
+                return unresolved('no jurisdiction supplied');
+            return rule.jurisdictions.includes(ctx.jurisdiction) ? applies() : notApplicable(`jurisdiction ${ctx.jurisdiction} is not one of ${rule.jurisdictions.join(', ')}`);
+        case 'effective': {
+            if (ctx.asOf == null)
+                return unresolved('no evaluation date supplied for an effective-date rule');
+            const day = dayOf(ctx.asOf);
+            if (day == null)
+                return unresolved(`the evaluation date ${ctx.asOf} is not a date`);
+            if (rule.from != null && day < rule.from)
+                return notApplicable(`not effective until ${rule.from}`);
+            if (rule.until != null && day > rule.until)
+                return notApplicable(`no longer effective after ${rule.until}`);
+            return applies();
+        }
+        case 'threshold': {
+            const read = thresholdValue(ctx.values?.[rule.field], rule.unit);
+            if ('reason' in read)
+                return unresolved(`${rule.field} ${read.reason}, so the threshold cannot be decided`);
+            const v = read.value;
+            const holds = rule.operator === 'gt' ? v > rule.value : rule.operator === 'gte' ? v >= rule.value : rule.operator === 'lt' ? v < rule.value : rule.operator === 'lte' ? v <= rule.value : v === rule.value;
+            return holds ? applies() : notApplicable(`${rule.field} ${v}${rule.unit == null ? '' : ` ${rule.unit}`} is not ${rule.operator} ${rule.value}`);
+        }
+        case 'unresolved':
+            return unresolved(`${rule.reason}${rule.source == null ? '' : ` (${rule.source})`}`);
+        default:
+            return unresolved(`rule ${String(rule.rule)} is not one this evaluator implements`);
+    }
+}
+/** The key under which a record declares fields inapplicable, and the shape of each declaration. */
+export const INAPPLICABLE_FIELDS_KEY = 'inapplicableFields';
+/** The declarations a payload carries under `inapplicableFields`, as field keys; malformed entries are ignored, never read as a declaration. */
+export function declaredInapplicable(payload) {
+    const raw = payload?.[INAPPLICABLE_FIELDS_KEY];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((d) => d != null && typeof d === 'object' && typeof d.field === 'string' && typeof d.reason === 'string' && d.reason.trim() !== '').map((d) => d.field);
+}
+/**
+ * A field's applicability under a context: a declaration under
+ * `inapplicableFields` answers not-applicable with the reason `declared`
+ * only where the rule would otherwise be unresolved or conditional, so a
+ * declaration cannot switch off a field that applies unconditionally; the
+ * rule answers otherwise.
+ */
+export function evaluateFieldApplicability(field, ctx = {}) {
+    const result = evaluateApplicability(field.applicability, ctx);
+    if (result.outcome !== 'unresolved' || !(ctx.declaredNotApplicable ?? []).includes(field.key))
+        return result;
+    return { outcome: 'not-applicable', reasons: ['declared: the record declares the field inapplicable under inapplicableFields'] };
+}
+/**
+ * The fields of a version 1 or version 2 manifest under a context: what
+ * applies, what does not, and what is unresolved with its reasons. The
+ * version 1 `fieldsFor` remains the reader for version 1 manifests with a
+ * bare category; this one takes the whole context.
+ */
+export function fieldsForV2(manifest, ctx = {}) {
+    const result = { applies: [], notApplicable: [], unresolved: [] };
+    for (const field of manifest.fields) {
+        const r = evaluateFieldApplicability(field, ctx);
+        if (r.outcome === 'applies')
+            result.applies.push(field);
+        else if (r.outcome === 'not-applicable')
+            result.notApplicable.push(field);
+        else
+            result.unresolved.push({ field, reasons: r.reasons });
+    }
+    return result;
+}
+const CAPTURED_AT_REGISTRATION = ['form', 'brand', 'platform'];
+function present(payload, key) {
+    const value = payload[key];
+    if (value === undefined || value === null || value === '')
+        return false;
+    if (Array.isArray(value) && value.length === 0)
+        return false;
+    return true;
+}
+/**
+ * Which required fields a payload lacks under a context, on three separate
+ * lists. A field whose applicability is unresolved is never missing and never
+ * satisfied; a field whose requirement status is anticipated, not to be
+ * displayed or under review is deferred and never blocks, so an adopter can
+ * keep incomplete draft data without a false failure or a false pass. A
+ * field the payload declares inapplicable under `inapplicableFields` is
+ * not-applicable where it would otherwise be unresolved.
+ */
+export function missingRequiredV2(manifest, payload, ctx = {}) {
+    const result = { missing: [], unresolved: [], deferred: [] };
+    // The payload's own declarations, unless the caller supplied the list.
+    const effective = ctx.declaredNotApplicable == null ? { ...ctx, declaredNotApplicable: declaredInapplicable(payload) } : ctx;
+    for (const field of manifest.fields) {
+        if (field.obligation !== 'required' || present(payload, field.key))
+            continue;
+        if (isFieldV2(field) && ['anticipated', 'not-to-be-displayed', 'needs-review'].includes(field.requirement.status)) {
+            result.deferred.push({ field, status: field.requirement.status });
+            continue;
+        }
+        const r = evaluateFieldApplicability(field, effective);
+        if (r.outcome === 'not-applicable')
+            continue;
+        if (r.outcome === 'unresolved') {
+            result.unresolved.push({ field, reasons: r.reasons });
+            continue;
+        }
+        if (CAPTURED_AT_REGISTRATION.includes(field.provenance.capture))
+            result.missing.push(field);
+    }
+    return result;
+}
+/** The category value a payload names for a manifest, read at the manifest's declared category key. */
+export function categoryOf(manifest, payload) {
+    const key = manifest.applicability.categoryKey;
+    if (key == null || payload == null)
+        return undefined;
+    const value = payload[key];
+    return typeof value === 'string' ? value : undefined;
+}
+//# sourceMappingURL=applicability.js.map

package/dist/applicability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applicability.js","sourceRoot":"","sources":["../src/applicability.ts"],"names":[],"mappings":"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"}

package/dist/combinations.d.ts

@@ -0,0 +1,30 @@
+export declare const BASELINE_ID = "native-baseline@1";
+/** The second recommended baseline: record version 2 with the managed-custody profile (conformance/baseline-native-2.json). */
+export declare const BASELINE_ID_2 = "native-baseline@2";
+export declare const BASELINE_IDS: readonly ["native-baseline@1", "native-baseline@2"];
+export type SelectionPurpose = 'read' | 'write' | 'claim';
+export interface DeploymentDeclaration {
+    operators?: number;
+    discovery?: 'none' | 'ship-slap' | 'static-peers';
+    gasp?: boolean;
+}
+export interface ProfileSelection {
+    baseline: string;
+    industry?: string;
+    exchange?: string[];
+    operator?: string;
+    deployment?: DeploymentDeclaration;
+    /** read: verify what exists; write: issue new states or claims; claim: state conformance to the selected profiles. */
+    purpose: SelectionPurpose;
+}
+export type SelectionConflictCode = 'baseline-unknown' | 'industry-unknown' | 'industry-superseded' | 'industry-draft' | 'exchange-unknown' | 'exchange-duplicate' | 'exchange-proposed' | 'exchange-artefacts-unpinned' | 'operator-unknown' | 'operator-proposed' | 'operator-single-with-federation-options' | 'operator-federation-needs-two' | 'operator-federation-without-discovery';
+export interface SelectionResult {
+    ok: boolean;
+    conflicts: Array<{
+        code: SelectionConflictCode;
+        detail: string;
+    }>;
+    notes: string[];
+}
+export declare function checkSelection(selection: ProfileSelection): SelectionResult;
+//# sourceMappingURL=combinations.d.ts.map

package/dist/combinations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combinations.d.ts","sourceRoot":"","sources":["../src/combinations.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,WAAW,sBAAsB,CAAA;AAC9C,+HAA+H;AAC/H,eAAO,MAAM,aAAa,sBAAsB,CAAA;AAChD,eAAO,MAAM,YAAY,qDAAwC,CAAA;AAEjE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAEzD,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,cAAc,CAAA;IACjD,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,qBAAqB,CAAA;IAClC,sHAAsH;IACtH,OAAO,EAAE,gBAAgB,CAAA;CAC1B;AAED,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB,kBAAkB,GAClB,qBAAqB,GACrB,gBAAgB,GAChB,kBAAkB,GAClB,oBAAoB,GACpB,mBAAmB,GACnB,6BAA6B,GAC7B,kBAAkB,GAClB,mBAAmB,GACnB,yCAAyC,GACzC,+BAA+B,GAC/B,uCAAuC,CAAA;AAE3C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAA;IACX,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,qBAAqB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACjE,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,GAAG,eAAe,CAoE3E"}

package/dist/combinations.js

@@ -0,0 +1,103 @@
+/**
+ * Profile combinations (`spec/conformance.md` §4, `spec/profiles.md`): an
+ * industry profile says what a passport carries, an exchange profile how a
+ * credential travels beside it, an operator profile how an index is run. They
+ * are selected together, and some selections contradict themselves: a new
+ * state under a superseded version, a conformance claim on a proposed profile
+ * whose artefacts were never pinned, a single operator declaring peers, a
+ * federation of one. `checkSelection` names every contradiction rather than
+ * choosing for the caller, and passes with notes when the selection is only
+ * unusual.
+ */
+import { EXCHANGE_PROFILE_IDS, OPERATOR_PROFILE_IDS, PROFILE_IDS, readExchangeProfile, readOperatorProfile } from './index.js';
+import { isManifestV2, readManifestAny } from './manifest-v2.js';
+export const BASELINE_ID = 'native-baseline@1';
+/** The second recommended baseline: record version 2 with the managed-custody profile (conformance/baseline-native-2.json). */
+export const BASELINE_ID_2 = 'native-baseline@2';
+export const BASELINE_IDS = [BASELINE_ID, BASELINE_ID_2];
+export function checkSelection(selection) {
+    const conflicts = [];
+    const notes = [];
+    const conflict = (code, detail) => { conflicts.push({ code, detail }); };
+    if (!BASELINE_IDS.includes(selection.baseline))
+        conflict('baseline-unknown', `${selection.baseline} is not a baseline this catalogue knows; the baselines are ${BASELINE_IDS.join(' and ')}`);
+    if (selection.industry != null) {
+        if (!PROFILE_IDS.includes(selection.industry)) {
+            conflict('industry-unknown', `${selection.industry} is not an industry profile in this catalogue`);
+        }
+        else {
+            const manifest = readManifestAny(selection.industry);
+            if (manifest.status === 'superseded') {
+                if (selection.purpose === 'read')
+                    notes.push(`${manifest.profile} is superseded by ${manifest.supersededBy}; states that declare it decode under it and are never reinterpreted`);
+                else
+                    conflict('industry-superseded', `${manifest.profile} is superseded by ${manifest.supersededBy}; a new state or claim is issued under the current version`);
+            }
+            else if (manifest.status === 'draft') {
+                // A draft successor is opt-in: a deployment may read and write under
+                // it by explicit version, and is told so; a conformance claim rests on
+                // the current version until the reviewed cutover marks it superseded.
+                const of = isManifestV2(manifest) && manifest.succession != null ? manifest.succession.of : 'the current version';
+                if (selection.purpose === 'claim')
+                    conflict('industry-draft', `${manifest.profile} is a draft successor to ${of}; a conformance claim rests on the current version`);
+                else
+                    notes.push(`${manifest.profile} is a draft: opt-in successor to ${of}, not yet the current version; a conformance claim rests on the current version`);
+            }
+        }
+    }
+    const seen = new Set();
+    for (const id of selection.exchange ?? []) {
+        if (seen.has(id)) {
+            conflict('exchange-duplicate', `${id} is selected twice`);
+            continue;
+        }
+        seen.add(id);
+        if (!EXCHANGE_PROFILE_IDS.includes(id)) {
+            conflict('exchange-unknown', `${id} is not an exchange profile in this catalogue`);
+            continue;
+        }
+        const profile = readExchangeProfile(id);
+        const unpinned = (profile.artefacts ?? []).filter((a) => a.retrieval === 'not-retrieved').map((a) => a.id);
+        if (selection.purpose === 'claim') {
+            if (profile.status !== 'current') {
+                conflict('exchange-proposed', `${id} is ${profile.status}; no conformance claim rests on a profile that is not current`);
+                if (unpinned.length > 0)
+                    conflict('exchange-artefacts-unpinned', `${id} has artefacts not retrieved and pinned: ${unpinned.join(', ')}`);
+            }
+            else if (unpinned.length > 0) {
+                // A current profile with an upstream artefact nobody could retrieve
+                // (the ledger's unassessed rows) supports the implemented-subset claim
+                // and never the full one; the ledger's claim gate is where that split
+                // is enforced, and the note points at it.
+                notes.push(`${id}: the claim covers the implemented subset; artefacts not retrieved (${unpinned.join(', ')}) keep the full-conformance claim blocked in the ledger`);
+            }
+        }
+        else if (profile.status !== 'current' || unpinned.length > 0) {
+            notes.push(`${id} is ${profile.status}${unpinned.length > 0 ? ` with unpinned artefacts (${unpinned.join(', ')})` : ''}; usable for a pilot, not for a claim`);
+        }
+    }
+    if (selection.operator != null) {
+        if (!OPERATOR_PROFILE_IDS.includes(selection.operator)) {
+            conflict('operator-unknown', `${selection.operator} is not an operator profile in this catalogue`);
+        }
+        else {
+            const profile = readOperatorProfile(selection.operator);
+            const d = selection.deployment ?? {};
+            if (selection.operator === 'single-operator@1') {
+                if ((d.operators ?? 1) > 1 || d.gasp === true || (d.discovery != null && d.discovery !== 'none')) {
+                    conflict('operator-single-with-federation-options', 'single-operator@1 declares one administration with discovery and synchronisation off; peers, GASP or advertisement belong to federated-operators@1');
+                }
+            }
+            else {
+                if ((d.operators ?? 1) < 2)
+                    conflict('operator-federation-needs-two', 'federated-operators@1 needs at least two independently administered operators; one operator is single-operator@1');
+                if (d.discovery == null || d.discovery === 'none')
+                    conflict('operator-federation-without-discovery', 'federated-operators@1 needs SHIP and SLAP or a declared static-peer profile so operators find each other; discovery none is single-operator@1');
+                if (selection.purpose === 'claim' && profile.status !== 'current')
+                    conflict('operator-proposed', `${selection.operator} is ${profile.status}; the independently administered exercise has not been run, so no claim rests on it`);
+            }
+        }
+    }
+    return { ok: conflicts.length === 0, conflicts, notes };
+}
+//# sourceMappingURL=combinations.js.map

package/dist/combinations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"combinations.js","sourceRoot":"","sources":["../src/combinations.ts"],"names":[],"mappings":"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"}