@async/api-contract 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial development version.

package/README.md

@@ -0,0 +1,150 @@
+# @async/api-contract
+
+`@async/api-contract` makes API compatibility explicit at the feature level. Instead of asking whether two package versions look compatible, a provider publishes the features it supports, a consumer records the features it requires, and CI checks whether the required surface is still a subset of the supported surface.
+
+**30-word value prop:** `@async/api-contract` turns API compatibility into feature-level contracts: publish what packages support, derive what consumers require, and catch breaking changes before versions, docs, or tests drift across Async workspaces during releases.
+
+Compatibility is feature-based, not package-version-based:
+
+```txt
+required.features subset_of supported.features
+```
+
+Package versions, release tags, docs text, and metadata do not decide compatibility.
+
+## What it produces
+
+- `api-contract.json`: the machine-readable contract a package publishes, including catalogs, supported surfaces, required surfaces, emitted surfaces, or usage evidence.
+- `Surface`: normalized runtime data with sorted unique feature ids and a stable hash.
+- `API_SURFACE.md`: a deterministic review ledger for maintainers and docs.
+- Impact reports: a quick way to see which consumers use removed, changed, or deprecated features before running expensive many-repo checks.
+
+## Quick start
+
+```ts
+import {
+  compareSurface,
+  createSurface,
+  defineFeatureCatalog,
+  deriveSurface
+} from "@async/api-contract";
+
+const catalog = defineFeatureCatalog({
+  format: "api-contract.catalog.v1",
+  contractId: "@async/user-api.response",
+  features: [
+    { id: "user.id", title: "User id field", releaseTag: "public", stability: "stable" },
+    { id: "user.email", title: "User email field", releaseTag: "public", stability: "stable" }
+  ]
+});
+
+const userResponse = {
+  id: "usr_123",
+  email: "ada@example.com"
+};
+
+const required = deriveSurface(userResponse, {
+  contractId: "@async/user-api.response",
+  catalog,
+  strictCatalog: true,
+  rules: [
+    {
+      name: "user-response-fields",
+      visit(value, context) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) return;
+        if ("id" in value) context.add("user.id");
+        if ("email" in value) context.add("user.email");
+      }
+    }
+  ]
+});
+
+const supported = createSurface({
+  contractId: "@async/user-api.response",
+  features: ["user.id", "user.email"]
+});
+
+const result = compareSurface(required, supported);
+
+console.log(required.features); // ["user.email", "user.id"]
+console.log(result.ok); // true
+```
+
+Host packages own shape validation and derivation rules. For example, `@async/pipeline` should validate branded declaration nodes before deriving a surface from them.
+
+## Policy checks
+
+Subset compatibility is the default. When a catalog is available, comparisons can also enforce release and lifecycle policy:
+
+```ts
+const result = compareSurface(required, supported, {
+  catalog,
+  allowedReleaseTags: ["public"],
+  deprecated: "warn",
+  removed: "error",
+  unknownFeatures: "error"
+});
+
+if (!result.ok) {
+  console.error(result.warnings);
+}
+```
+
+## Type-only contracts
+
+Use `@async/api-contract/types` for app code and virtual imports that should express a contract without emitting runtime JavaScript.
+
+```ts
+import type {
+  AssertCompatible,
+  Expect,
+  RequiresContract,
+  SupportsContract
+} from "@async/api-contract/types";
+
+type UsesPipeline = RequiresContract<"@async/pipeline.declaration">;
+
+type UsesShellStep = RequiresContract<
+  "@async/pipeline.declaration",
+  "task.run" | "step.shell"
+>;
+
+type HostSupport = SupportsContract<
+  "@async/pipeline.declaration",
+  "task.run" | "step.shell" | "agent.stdoutTo"
+>;
+
+type Check = Expect<AssertCompatible<UsesShellStep, HostSupport>>;
+```
+
+The default is forward-compatible rather than untyped: known fields stay precise, exact feature unions are supported, and option maps allow future `x-*` extension fields.
+
+## Release and stability tags
+
+Catalog features can carry API Extractor-style maturity metadata:
+
+- `public`
+- `beta`
+- `alpha`
+- `internal`
+
+Project-facing stability labels such as `stable`, `preview`, `experimental`, `generated`, `dev-only`, and `internal` are docs and policy metadata. They do not affect `surfaceHash()`.
+
+## CLI
+
+```sh
+api-contract check --manifest api-contract.json
+api-contract ledger --manifest api-contract.json --out API_SURFACE.md
+api-contract ledger --manifest api-contract.json --check API_SURFACE.md
+api-contract diff --before old-api-contract.json --after api-contract.json
+api-contract impact --before old-api-contract.json --after api-contract.json --consumers consumers.json
+api-contract usage scan --target src --package-name @async/consumer --dependency @async/pipeline --catalog api-contract.json --out api-usage.json
+```
+
+`impact` is intended as a cheap preflight for explicit many-repo impact runs. Read the latest consumer manifests or usage files first; then run full dependent repo checks only for consumers that actually use changed features.
+
+`usage scan` is a line-oriented source preflight. It records dependency and feature-string evidence, but it is not a full parser or proof of semantic usage.
+
+## Relationship to @async/claims
+
+`@async/claims` can wrap surfaces with issuer, evidence, trust, policy, and signatures. It should not redefine feature ids, hashes, derivation, or compatibility rules.

package/dist/catalog.d.ts

@@ -0,0 +1,4 @@
+import type { FeatureCatalog } from "./model.js";
+export declare function defineFeatureCatalog(catalog: FeatureCatalog): FeatureCatalog;
+export declare function catalogFeatureIds(catalog: FeatureCatalog): Set<string>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,YAAY,CAAC;AAK9D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CA0B5E;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,CAAC,CAEtE"}

package/dist/catalog.js

@@ -0,0 +1,62 @@
+const releaseTags = new Set(["public", "beta", "alpha", "internal"]);
+const lifecycles = new Set(["active", "deprecated", "removed"]);
+export function defineFeatureCatalog(catalog) {
+    assertObject(catalog, "catalog");
+    if (catalog.format !== "api-contract.catalog.v1") {
+        throw new Error("FeatureCatalog.format must be api-contract.catalog.v1");
+    }
+    assertNonEmptyString(catalog.contractId, "FeatureCatalog.contractId");
+    if (!Array.isArray(catalog.features)) {
+        throw new Error("FeatureCatalog.features must be an array");
+    }
+    const seen = new Set();
+    const features = catalog.features.map((feature) => normalizeFeatureSpec(feature));
+    for (const feature of features) {
+        if (seen.has(feature.id)) {
+            throw new Error(`Duplicate feature id: ${feature.id}`);
+        }
+        seen.add(feature.id);
+    }
+    return {
+        ...copyExtensionFields(catalog),
+        format: "api-contract.catalog.v1",
+        contractId: catalog.contractId,
+        ...(catalog.title === undefined ? {} : { title: catalog.title }),
+        features: features.sort((a, b) => a.id.localeCompare(b.id))
+    };
+}
+export function catalogFeatureIds(catalog) {
+    return new Set(catalog.features.map((feature) => feature.id));
+}
+function normalizeFeatureSpec(feature) {
+    assertObject(feature, "FeatureSpec");
+    assertNonEmptyString(feature.id, "FeatureSpec.id");
+    assertNonEmptyString(feature.title, "FeatureSpec.title");
+    if (!releaseTags.has(feature.releaseTag)) {
+        throw new Error(`FeatureSpec.releaseTag must be one of public, beta, alpha, internal for ${feature.id}`);
+    }
+    if (feature.lifecycle !== undefined && !lifecycles.has(feature.lifecycle)) {
+        throw new Error(`FeatureSpec.lifecycle must be active, deprecated, or removed for ${feature.id}`);
+    }
+    return { ...feature };
+}
+function assertObject(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+}
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+}
+function copyExtensionFields(value) {
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (key.startsWith("x-")) {
+            out[key] = entry;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+import { parsePackageContractManifest } from "./manifest.js";
+import { renderApiSurfaceMarkdown } from "./ledger.js";
+import { diffPackageContracts } from "./diff.js";
+import { createImpactReport } from "./impact.js";
+import { scanUsageTarget } from "./usage-scan.js";
+function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function argValue(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function readManifest(path) {
+    return parsePackageContractManifest(readJson(path));
+}
+function writeJsonOrStdout(value, outPath) {
+    const text = `${JSON.stringify(value, null, 2)}
+`;
+    if (outPath)
+        writeFileSync(outPath, text);
+    else
+        process.stdout.write(text);
+}
+function readConsumers(path) {
+    const value = readJson(path);
+    if (Array.isArray(value))
+        return value.map(parsePackageContractManifest);
+    if (typeof value === "object" && value !== null && Array.isArray(value.manifests)) {
+        return value.manifests.map(parsePackageContractManifest);
+    }
+    return [parsePackageContractManifest(value)];
+}
+const args = process.argv.slice(2);
+const command = args[0];
+try {
+    if (command === "check") {
+        const manifestPath = argValue(args, "--manifest");
+        if (!manifestPath)
+            throw new Error("Missing --manifest <file>");
+        parsePackageContractManifest(readJson(manifestPath));
+        console.log(`ok ${manifestPath}`);
+    }
+    else if (command === "ledger") {
+        const manifestPath = argValue(args, "--manifest");
+        if (!manifestPath)
+            throw new Error("Missing --manifest <file>");
+        const manifest = readManifest(manifestPath);
+        const markdown = renderApiSurfaceMarkdown({ manifest });
+        const checkPath = argValue(args, "--check");
+        if (checkPath) {
+            const existing = readFileSync(checkPath, "utf8");
+            if (existing !== markdown)
+                throw new Error(`${checkPath} is out of date`);
+            console.log(`ok ${checkPath}`);
+        }
+        else {
+            const outPath = argValue(args, "--out");
+            if (outPath)
+                writeFileSync(outPath, markdown);
+            else
+                process.stdout.write(markdown);
+        }
+    }
+    else if (command === "diff") {
+        const beforePath = argValue(args, "--before");
+        const afterPath = argValue(args, "--after");
+        if (!beforePath || !afterPath)
+            throw new Error("Missing --before <file> or --after <file>");
+        writeJsonOrStdout(diffPackageContracts(readManifest(beforePath), readManifest(afterPath)), argValue(args, "--out"));
+    }
+    else if (command === "impact") {
+        const beforePath = argValue(args, "--before");
+        const afterPath = argValue(args, "--after");
+        const consumersPath = argValue(args, "--consumers");
+        if (!beforePath || !afterPath || !consumersPath)
+            throw new Error("Missing --before <file>, --after <file>, or --consumers <file>");
+        writeJsonOrStdout(createImpactReport({ before: readManifest(beforePath), after: readManifest(afterPath), consumers: readConsumers(consumersPath) }), argValue(args, "--out"));
+    }
+    else if (command === "usage" && args[1] === "scan") {
+        const target = argValue(args, "--target");
+        const dependencyName = argValue(args, "--dependency");
+        const catalogPath = argValue(args, "--catalog");
+        const packageName = argValue(args, "--package-name") ?? "unknown";
+        if (!target || !dependencyName || !catalogPath)
+            throw new Error("Missing --target <path>, --dependency <name>, or --catalog <manifest>");
+        const manifest = readManifest(catalogPath);
+        const catalog = manifest.catalogs?.[0];
+        if (!catalog)
+            throw new Error(`${catalogPath} does not contain a catalog`);
+        writeJsonOrStdout({
+            format: "api-contract.package.v1",
+            packageName,
+            usage: [scanUsageTarget({ target, dependencyName, packageName, catalog })]
+        }, argValue(args, "--out"));
+    }
+    else {
+        throw new Error("Usage: api-contract check|ledger|diff|impact|usage scan");
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/compare.d.ts

@@ -0,0 +1,4 @@
+import type { ComparePolicy, ContractSet, Surface, SurfaceComparison } from "./model.js";
+export declare function compareSurface(required: Surface, supported: Surface, policy?: ComparePolicy): SurfaceComparison;
+export declare function compareContractSets(required: ContractSet, supported: ContractSet, policy?: ComparePolicy): SurfaceComparison;
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAA0C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIjI,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAE,aAAkB,GAAG,iBAAiB,CAsBnH;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAE,aAAkB,GAAG,iBAAiB,CA4BhI"}

package/dist/compare.js

@@ -0,0 +1,101 @@
+export function compareSurface(required, supported, policy = {}) {
+    if (required.contractId !== supported.contractId) {
+        return {
+            ok: false,
+            missing: [...required.features],
+            unsupported: [...supported.features],
+            warnings: [`Contract id mismatch: required ${required.contractId}, supported ${supported.contractId}`]
+        };
+    }
+    const supportedFeatures = new Set(supported.features);
+    const requiredFeatures = new Set(required.features);
+    const missing = required.features.filter((feature) => !supportedFeatures.has(feature));
+    const unsupported = supported.features.filter((feature) => !requiredFeatures.has(feature));
+    const policyResult = evaluatePolicy(required, policy);
+    return {
+        ok: missing.length === 0 && policyResult.ok,
+        missing,
+        unsupported,
+        warnings: policyResult.warnings
+    };
+}
+export function compareContractSets(required, supported, policy = {}) {
+    const supportedByContract = new Map(supported.surfaces.map((surface) => [surface.contractId, surface]));
+    const missing = [];
+    const unsupported = [];
+    const warnings = [];
+    let ok = true;
+    for (const requiredSurface of required.surfaces) {
+        const supportedSurface = supportedByContract.get(requiredSurface.contractId);
+        if (!supportedSurface) {
+            ok = false;
+            missing.push(...requiredSurface.features.map((feature) => `${requiredSurface.contractId}:${feature}`));
+            warnings.push(`Missing supported surface for ${requiredSurface.contractId}`);
+            continue;
+        }
+        const comparison = compareSurface(requiredSurface, supportedSurface, policy);
+        if (!comparison.ok)
+            ok = false;
+        missing.push(...comparison.missing);
+        unsupported.push(...comparison.unsupported);
+        warnings.push(...comparison.warnings);
+    }
+    return {
+        ok: ok && missing.length === 0,
+        missing,
+        unsupported,
+        warnings
+    };
+}
+function evaluatePolicy(required, policy) {
+    const features = policyFeatureMap(required.contractId, policy);
+    if (!features)
+        return { ok: true, warnings: [] };
+    const warnings = [];
+    const errors = [];
+    const report = (action, message) => {
+        if (action === "warn")
+            warnings.push(message);
+        if (action === "error")
+            errors.push(message);
+    };
+    for (const featureId of required.features) {
+        const feature = features.get(featureId);
+        if (!feature) {
+            report(policy.unknownFeatures, `Unknown feature in ${required.contractId}: ${featureId}`);
+            continue;
+        }
+        if (policy.allowedReleaseTags && !policy.allowedReleaseTags.includes(feature.releaseTag)) {
+            errors.push(`Feature ${featureId} has release tag ${feature.releaseTag}, which is not allowed by policy`);
+        }
+        if (feature.lifecycle === "deprecated") {
+            report(policy.deprecated, `Feature ${featureId} is deprecated`);
+        }
+        if (feature.lifecycle === "removed") {
+            report(policy.removed, `Feature ${featureId} is removed`);
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        warnings: [...warnings, ...errors.map((error) => `Policy error: ${error}`)]
+    };
+}
+function policyFeatureMap(contractId, policy) {
+    const catalogs = policyCatalogs(policy).filter((catalog) => catalog.contractId === contractId);
+    if (catalogs.length === 0)
+        return undefined;
+    const features = new Map();
+    for (const catalog of catalogs) {
+        for (const feature of catalog.features) {
+            features.set(feature.id, feature);
+        }
+    }
+    return features;
+}
+function policyCatalogs(policy) {
+    return [
+        ...(policy.catalog ? [policy.catalog] : []),
+        ...(policy.catalogs ?? [])
+    ];
+}
+//# sourceMappingURL=compare.js.map

package/dist/compare.js.map

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

package/dist/derive.d.ts

@@ -0,0 +1,3 @@
+import type { DeriveSurfaceOptions, Surface } from "./model.js";
+export declare function deriveSurface(value: unknown, options: DeriveSurfaceOptions): Surface;
+//# sourceMappingURL=derive.d.ts.map

package/dist/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiB,oBAAoB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CA+CpF"}

package/dist/derive.js

@@ -0,0 +1,61 @@
+import { catalogFeatureIds } from "./catalog.js";
+import { createSurface } from "./surface.js";
+export function deriveSurface(value, options) {
+    const features = new Set();
+    const knownFeatures = options.catalog ? catalogFeatureIds(options.catalog) : undefined;
+    const visited = new WeakSet();
+    const addFeature = (feature) => {
+        if (options.strictCatalog && knownFeatures && !knownFeatures.has(feature)) {
+            throw new Error(`Unknown feature emitted by derivation rule: ${feature}`);
+        }
+        features.add(feature);
+    };
+    const walk = (node, path) => {
+        if (isObject(node)) {
+            if (visited.has(node))
+                return;
+            visited.add(node);
+        }
+        const context = { path, add: addFeature };
+        const customChildren = [];
+        let hasCustomChildren = false;
+        for (const rule of options.rules) {
+            rule.visit(node, context);
+            if (rule.children) {
+                hasCustomChildren = true;
+                for (const child of rule.children(node, context)) {
+                    customChildren.push(child);
+                }
+            }
+        }
+        if (hasCustomChildren) {
+            for (const [index, child] of customChildren.entries()) {
+                walk(child, [...path, index]);
+            }
+            return;
+        }
+        for (const [key, child] of defaultChildren(node)) {
+            walk(child, [...path, key]);
+        }
+    };
+    walk(value, []);
+    return createSurface({ contractId: options.contractId, features });
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function defaultChildren(value) {
+    if (!isObject(value))
+        return [];
+    if (Array.isArray(value)) {
+        return value.map((entry, index) => [index, entry]);
+    }
+    if (value instanceof Map) {
+        return [...value.entries()].map(([key, entry]) => [String(key), entry]);
+    }
+    if (value instanceof Set) {
+        return [...value.values()].map((entry, index) => [index, entry]);
+    }
+    return Object.entries(value);
+}
+//# sourceMappingURL=derive.js.map

package/dist/derive.js.map

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

package/dist/diff.d.ts

@@ -0,0 +1,3 @@
+import type { ContractDiff, PackageContractManifest } from "./model.js";
+export declare function diffPackageContracts(before: PackageContractManifest, after: PackageContractManifest): ContractDiff;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAa,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEnF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,uBAAuB,EAAE,KAAK,EAAE,uBAAuB,GAAG,YAAY,CA0BlH"}

package/dist/diff.js

@@ -0,0 +1,38 @@
+export function diffPackageContracts(before, after) {
+    const beforeFeatures = featureMap(before);
+    const afterFeatures = featureMap(after);
+    const addedFeatures = [];
+    const removedFeatures = [];
+    const changedFeatures = [];
+    const deprecatedFeatures = [];
+    for (const id of afterFeatures.keys()) {
+        if (!beforeFeatures.has(id))
+            addedFeatures.push(id);
+    }
+    for (const id of beforeFeatures.keys()) {
+        if (!afterFeatures.has(id))
+            removedFeatures.push(id);
+    }
+    for (const [id, feature] of afterFeatures) {
+        const previous = beforeFeatures.get(id);
+        if (previous && JSON.stringify(previous) !== JSON.stringify(feature))
+            changedFeatures.push(id);
+        if (feature.lifecycle === "deprecated")
+            deprecatedFeatures.push(id);
+    }
+    return {
+        addedFeatures: addedFeatures.sort(),
+        removedFeatures: removedFeatures.sort(),
+        changedFeatures: changedFeatures.sort(),
+        deprecatedFeatures: deprecatedFeatures.sort()
+    };
+}
+function featureMap(manifest) {
+    const out = new Map();
+    for (const catalog of manifest.catalogs ?? []) {
+        for (const feature of catalog.features)
+            out.set(feature.id, feature);
+    }
+    return out;
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,oBAAoB,CAAC,MAA+B,EAAE,KAA8B;IAClG,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,aAAa,GAAgB,EAAE,CAAC;IACtC,MAAM,eAAe,GAAgB,EAAE,CAAC;IACxC,MAAM,eAAe,GAAgB,EAAE,CAAC;IACxC,MAAM,kBAAkB,GAAgB,EAAE,CAAC;IAE3C,KAAK,MAAM,EAAE,IAAI,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,KAAK,MAAM,EAAE,IAAI,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC;QACvC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,aAAa,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACxC,IAAI,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YAAE,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/F,IAAK,OAAkC,CAAC,SAAS,KAAK,YAAY;YAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC;IAED,OAAO;QACL,aAAa,EAAE,aAAa,CAAC,IAAI,EAAE;QACnC,eAAe,EAAE,eAAe,CAAC,IAAI,EAAE;QACvC,eAAe,EAAE,eAAe,CAAC,IAAI,EAAE;QACvC,kBAAkB,EAAE,kBAAkB,CAAC,IAAI,EAAE;KAC9C,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,QAAiC;IACnD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAmB,CAAC;IACvC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QAC9C,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ;YAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/hash.d.ts

@@ -0,0 +1,8 @@
+import type { ContractId, FeatureId, SurfaceHash } from "./model.js";
+export declare function normalizeFeatureIds(features: Iterable<FeatureId>): FeatureId[];
+export declare function surfaceHash(input: {
+    contractId: ContractId;
+    features: Iterable<FeatureId>;
+}): SurfaceHash;
+export declare function hashJson(value: unknown): SurfaceHash;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAErE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,SAAS,EAAE,CAE9E;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAA;CAAE,GAAG,WAAW,CAMzG;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAEpD"}

package/dist/hash.js

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+export function normalizeFeatureIds(features) {
+    return [...new Set([...features])].sort((a, b) => a.localeCompare(b));
+}
+export function surfaceHash(input) {
+    const payload = JSON.stringify({
+        contractId: input.contractId,
+        features: normalizeFeatureIds(input.features)
+    });
+    return `sha256:${createHash("sha256").update(payload).digest("hex")}`;
+}
+export function hashJson(value) {
+    return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,UAAU,mBAAmB,CAAC,QAA6B;IAC/D,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAgE;IAC1F,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;KAC9C,CAAC,CAAC;IACH,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAiB,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAiB,CAAC;AACrG,CAAC"}