@async/api-contract 0.1.0

package/dist/impact.d.ts

@@ -0,0 +1,7 @@
+import type { ImpactReport, PackageContractManifest } from "./model.js";
+export declare function createImpactReport(input: {
+    before: PackageContractManifest;
+    after: PackageContractManifest;
+    consumers: readonly PackageContractManifest[];
+}): ImpactReport;
+//# sourceMappingURL=impact.d.ts.map

package/dist/impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../src/impact.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAgB,MAAM,YAAY,CAAC;AAEtF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,uBAAuB,CAAC;IAChC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC/C,GAAG,YAAY,CAsBf"}

package/dist/impact.js

@@ -0,0 +1,25 @@
+import { diffPackageContracts } from "./diff.js";
+export function createImpactReport(input) {
+    const diff = diffPackageContracts(input.before, input.after);
+    const relevant = new Set([...diff.removedFeatures, ...diff.changedFeatures, ...diff.deprecatedFeatures]);
+    const impactedConsumers = [];
+    const unaffectedConsumers = [];
+    for (const consumer of input.consumers) {
+        for (const usage of consumer.usage ?? []) {
+            const impacted = usage.surface.features.some((feature) => relevant.has(feature));
+            if (impacted)
+                impactedConsumers.push(usage);
+            else
+                unaffectedConsumers.push(usage);
+        }
+    }
+    return {
+        ok: impactedConsumers.length === 0,
+        providerPackage: input.after.packageName,
+        removedFeatures: diff.removedFeatures,
+        changedFeatures: [...new Set([...diff.changedFeatures, ...diff.deprecatedFeatures])].sort(),
+        impactedConsumers,
+        unaffectedConsumers
+    };
+}
+//# sourceMappingURL=impact.js.map

package/dist/impact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact.js","sourceRoot":"","sources":["../src/impact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGjD,MAAM,UAAU,kBAAkB,CAAC,KAIlC;IACC,MAAM,IAAI,GAAG,oBAAoB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACzG,MAAM,iBAAiB,GAAmB,EAAE,CAAC;IAC7C,MAAM,mBAAmB,GAAmB,EAAE,CAAC;IAE/C,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YACzC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACjF,IAAI,QAAQ;gBAAE,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;gBACvC,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,iBAAiB,CAAC,MAAM,KAAK,CAAC;QAClC,eAAe,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW;QACxC,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,eAAe,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;QAC3F,iBAAiB;QACjB,mBAAmB;KACpB,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./model.js";
+export * from "./catalog.js";
+export * from "./hash.js";
+export * from "./surface.js";
+export * from "./compare.js";
+export * from "./derive.js";
+export * from "./manifest.js";
+export * from "./ledger.js";
+export * from "./diff.js";
+export * from "./impact.js";
+export * from "./usage-scan.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./model.js";
+export * from "./catalog.js";
+export * from "./hash.js";
+export * from "./surface.js";
+export * from "./compare.js";
+export * from "./derive.js";
+export * from "./manifest.js";
+export * from "./ledger.js";
+export * from "./diff.js";
+export * from "./impact.js";
+export * from "./usage-scan.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/ledger.d.ts

@@ -0,0 +1,3 @@
+import type { RenderLedgerInput } from "./model.js";
+export declare function renderApiSurfaceMarkdown(input: RenderLedgerInput): string;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,iBAAiB,EAAW,MAAM,YAAY,CAAC;AAE1E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAiCzE"}

package/dist/ledger.js

@@ -0,0 +1,78 @@
+export function renderApiSurfaceMarkdown(input) {
+    const manifest = input.manifest;
+    const lines = [];
+    lines.push(`# ${input.title ?? `${manifest.packageName} API Surface Ledger`}`);
+    lines.push("");
+    lines.push(input.reviewRule ?? "This file is the generated review ledger for semantic API contract features. It is current-state contract documentation, not a changelog or tutorial.");
+    lines.push("");
+    for (const catalog of manifest.catalogs ?? []) {
+        lines.push(`## ${catalog.title ?? catalog.contractId}`);
+        lines.push("");
+        lines.push(`Contract: \`${catalog.contractId}\``);
+        lines.push("");
+        const grouped = groupFeatures(catalog.features);
+        for (const [group, features] of grouped) {
+            lines.push(`### ${titleCase(group)}`);
+            lines.push("");
+            lines.push("| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |");
+            lines.push("| --- | --- | --- | --- | --- | --- | --- |");
+            for (const feature of features) {
+                lines.push(`| \`${escapeCell(feature.id)}\` | ${escapeCell(feature.title)} | ${feature.releaseTag} | ${feature.stability ?? ""} | ${feature.lifecycle ?? "active"} | ${feature.replacedBy ? `\`${escapeCell(feature.replacedBy)}\`` : ""} | ${feature.docsUrl ? `[docs](${feature.docsUrl})` : ""} |`);
+            }
+            lines.push("");
+        }
+    }
+    pushSurfaceSection(lines, "Supported Surfaces", manifest.supported ?? []);
+    pushSurfaceSection(lines, "Required Surfaces", manifest.required ?? []);
+    pushSurfaceSection(lines, "Emitted Surfaces", manifest.emits ?? []);
+    pushLifecycleSummary(lines, manifest.catalogs?.flatMap((catalog) => [...catalog.features]) ?? []);
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+function groupFeatures(features) {
+    const groups = new Map();
+    for (const feature of features) {
+        const group = feature.group ?? "features";
+        const current = groups.get(group) ?? [];
+        current.push(feature);
+        groups.set(group, current);
+    }
+    return [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([group, entries]) => [group, entries.sort((a, b) => a.id.localeCompare(b.id))]);
+}
+function pushSurfaceSection(lines, title, surfaces) {
+    if (surfaces.length === 0)
+        return;
+    lines.push(`## ${title}`);
+    lines.push("");
+    lines.push("| Contract | Hash | Features |");
+    lines.push("| --- | --- | --- |");
+    for (const surface of [...surfaces].sort((a, b) => a.contractId.localeCompare(b.contractId))) {
+        lines.push(`| \`${escapeCell(surface.contractId)}\` | \`${surface.hash}\` | ${surface.features.map((feature) => `\`${escapeCell(feature)}\``).join(", ")} |`);
+    }
+    lines.push("");
+}
+function pushLifecycleSummary(lines, features) {
+    const tracked = features.filter((feature) => feature.lifecycle === "deprecated" || feature.lifecycle === "removed");
+    if (tracked.length === 0)
+        return;
+    lines.push("## Deprecated And Removed Features");
+    lines.push("");
+    lines.push("| Feature | Lifecycle | Since | Replacement |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const feature of tracked.sort((a, b) => a.id.localeCompare(b.id))) {
+        lines.push(`| \`${escapeCell(feature.id)}\` | ${feature.lifecycle ?? "active"} | ${feature.deprecatedSince ?? feature.removedSince ?? ""} | ${feature.replacedBy ? `\`${escapeCell(feature.replacedBy)}\`` : ""} |`);
+    }
+    lines.push("");
+}
+function titleCase(value) {
+    return value
+        .split(/[._ -]+/g)
+        .filter(Boolean)
+        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+        .join(" ");
+}
+function escapeCell(value) {
+    return value.replaceAll("|", "\\|");
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

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

package/dist/manifest.d.ts

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

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAkB,uBAAuB,EAAyB,MAAM,YAAY,CAAC;AAEjG,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAiBpF"}

package/dist/manifest.js

@@ -0,0 +1,62 @@
+import { defineFeatureCatalog } from "./catalog.js";
+import { createSurface } from "./surface.js";
+export function parsePackageContractManifest(value) {
+    assertObject(value, "PackageContractManifest");
+    if (value.format !== "api-contract.package.v1") {
+        throw new Error("PackageContractManifest.format must be api-contract.package.v1");
+    }
+    assertNonEmptyString(value.packageName, "PackageContractManifest.packageName");
+    return {
+        ...copyExtensionFields(value),
+        format: "api-contract.package.v1",
+        packageName: value.packageName,
+        ...(value.catalogs === undefined ? {} : { catalogs: parseArray(value.catalogs, "catalogs").map((catalog) => defineFeatureCatalog(catalog)) }),
+        ...(value.supported === undefined ? {} : { supported: parseArray(value.supported, "supported").map(parseSurface) }),
+        ...(value.required === undefined ? {} : { required: parseArray(value.required, "required").map(parseSurface) }),
+        ...(value.emits === undefined ? {} : { emits: parseArray(value.emits, "emits").map(parseSurface) }),
+        ...(value.usage === undefined ? {} : { usage: parseArray(value.usage, "usage").map((usage) => usage) })
+    };
+}
+function parseSurface(value) {
+    assertObject(value, "Surface");
+    if (value.format !== "api-contract.surface.v1") {
+        throw new Error("Surface.format must be api-contract.surface.v1");
+    }
+    assertNonEmptyString(value.contractId, "Surface.contractId");
+    const features = parseArray(value.features, "Surface.features");
+    for (const feature of features)
+        assertNonEmptyString(feature, "Surface.features[]");
+    const meta = value.meta === undefined ? undefined : value.meta;
+    const surface = meta === undefined
+        ? createSurface({ contractId: value.contractId, features: features })
+        : createSurface({ contractId: value.contractId, features: features, meta });
+    if (typeof value.hash === "string" && value.hash !== surface.hash) {
+        throw new Error(`Surface.hash mismatch for ${value.contractId}: expected ${surface.hash}, got ${value.hash}`);
+    }
+    return surface;
+}
+function parseArray(value, label) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${label} must be an array`);
+    }
+    return value;
+}
+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=manifest.js.map

package/dist/manifest.js.map

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

package/dist/model.d.ts

@@ -0,0 +1,125 @@
+export type ContractId = string;
+export type FeatureId = string;
+export type SurfaceHash = `sha256:${string}`;
+export type ReleaseTag = "public" | "beta" | "alpha" | "internal";
+export type KnownStabilityLabel = "stable" | "preview" | "experimental" | "generated" | "dev-only" | "internal";
+export type StabilityLabel = KnownStabilityLabel | (string & {});
+export type FeatureLifecycle = "active" | "deprecated" | "removed";
+export type ExtensionFields = {
+    readonly [key: `x-${string}`]: unknown;
+};
+export interface FeatureSpec extends ExtensionFields {
+    id: FeatureId;
+    title: string;
+    releaseTag: ReleaseTag;
+    stability?: StabilityLabel;
+    lifecycle?: FeatureLifecycle;
+    description?: string;
+    docsUrl?: string;
+    since?: string;
+    deprecatedSince?: string;
+    removedSince?: string;
+    replacedBy?: FeatureId;
+    group?: string;
+}
+export interface FeatureCatalog extends ExtensionFields {
+    format: "api-contract.catalog.v1";
+    contractId: ContractId;
+    title?: string;
+    features: readonly FeatureSpec[];
+}
+export interface Surface extends ExtensionFields {
+    format: "api-contract.surface.v1";
+    contractId: ContractId;
+    features: readonly FeatureId[];
+    hash: SurfaceHash;
+    meta?: Record<string, unknown>;
+}
+export interface ContractSet extends ExtensionFields {
+    format: "api-contract.set.v1";
+    surfaces: readonly Surface[];
+    hash: SurfaceHash;
+}
+export interface PackageContractManifest extends ExtensionFields {
+    format: "api-contract.package.v1";
+    packageName: string;
+    catalogs?: readonly FeatureCatalog[];
+    supported?: readonly Surface[];
+    required?: readonly Surface[];
+    emits?: readonly Surface[];
+    usage?: readonly UsageSurface[];
+}
+export interface ComparePolicy extends ExtensionFields {
+    catalog?: FeatureCatalog;
+    catalogs?: readonly FeatureCatalog[];
+    allowedReleaseTags?: readonly ReleaseTag[];
+    deprecated?: "allow" | "warn" | "error";
+    removed?: "allow" | "warn" | "error";
+    unknownFeatures?: "allow" | "warn" | "error";
+}
+export interface SurfaceComparison {
+    ok: boolean;
+    missing: readonly FeatureId[];
+    unsupported: readonly FeatureId[];
+    warnings: readonly string[];
+}
+export interface DeriveRule {
+    name: string;
+    visit(value: unknown, context: DeriveContext): void;
+    children?(value: unknown, context: DeriveContext): Iterable<unknown>;
+}
+export interface DeriveContext {
+    path: readonly PropertyKey[];
+    add(feature: FeatureId): void;
+}
+export interface DeriveSurfaceOptions {
+    contractId: ContractId;
+    rules: readonly DeriveRule[];
+    catalog?: FeatureCatalog;
+    strictCatalog?: boolean;
+}
+export interface UsageLocation {
+    file: string;
+    line?: number;
+    importPath?: string;
+    symbol?: string;
+    feature?: FeatureId;
+}
+export interface UsageSurface {
+    packageName: string;
+    dependencyName: string;
+    surface: Surface;
+    evidence: "published-manifest" | "type-contract" | "runtime-derived" | "source-scan";
+    locations?: readonly UsageLocation[];
+}
+export interface ImpactReport {
+    ok: boolean;
+    providerPackage: string;
+    removedFeatures: readonly FeatureId[];
+    changedFeatures: readonly FeatureId[];
+    impactedConsumers: readonly UsageSurface[];
+    unaffectedConsumers: readonly UsageSurface[];
+}
+export interface ContractDiff {
+    addedFeatures: readonly FeatureId[];
+    removedFeatures: readonly FeatureId[];
+    changedFeatures: readonly FeatureId[];
+    deprecatedFeatures: readonly FeatureId[];
+}
+export interface LedgerConfig extends ExtensionFields {
+    title?: string;
+    reviewRule?: string;
+    sections?: readonly LedgerSection[];
+}
+export interface LedgerSection extends ExtensionFields {
+    id: string;
+    title: string;
+    type: "features" | "surfaces" | "package-exports" | "cli" | "runtime" | "http" | "generated" | "config" | "internal-boundaries";
+    groups?: readonly string[];
+}
+export interface RenderLedgerInput {
+    manifest: PackageContractManifest;
+    title?: string;
+    reviewRule?: string;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAChC,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAC/B,MAAM,MAAM,WAAW,GAAG,UAAU,MAAM,EAAE,CAAC;AAE7C,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAElE,MAAM,MAAM,mBAAmB,GAC3B,QAAQ,GACR,SAAS,GACT,cAAc,GACd,WAAW,GACX,UAAU,GACV,UAAU,CAAC;AAEf,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,GAAG,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC;CACxC,CAAC;AAEF,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,MAAM,EAAE,yBAAyB,CAAC;IAClC,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,OAAQ,SAAQ,eAAe;IAC9C,MAAM,EAAE,yBAAyB,CAAC;IAClC,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,MAAM,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,MAAM,EAAE,yBAAyB,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC/B,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC3C,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACxC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,eAAe,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;CAC9C;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IAC9B,WAAW,EAAE,SAAS,SAAS,EAAE,CAAC;IAClC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAC7B,GAAG,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,oBAAoB,GAAG,eAAe,GAAG,iBAAiB,GAAG,aAAa,CAAC;IACrF,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,eAAe,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,iBAAiB,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,mBAAmB,EAAE,SAAS,YAAY,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,eAAe,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,eAAe,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,kBAAkB,EAAE,SAAS,SAAS,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EACA,UAAU,GACV,UAAU,GACV,iBAAiB,GACjB,KAAK,GACL,SAAS,GACT,MAAM,GACN,WAAW,GACX,QAAQ,GACR,qBAAqB,CAAC;IAC1B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

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

package/dist/surface.d.ts

@@ -0,0 +1,8 @@
+import type { ContractSet, Surface } from "./model.js";
+export declare function createSurface(input: {
+    contractId: string;
+    features: Iterable<string>;
+    meta?: Record<string, unknown>;
+}): Surface;
+export declare function createContractSet(surfaces: Iterable<Surface>): ContractSet;
+//# sourceMappingURL=surface.d.ts.map

package/dist/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGvD,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GAAG,OAAO,CAaV;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,WAAW,CAY1E"}

package/dist/surface.js

@@ -0,0 +1,26 @@
+import { hashJson, normalizeFeatureIds, surfaceHash } from "./hash.js";
+export function createSurface(input) {
+    const surface = {
+        format: "api-contract.surface.v1",
+        contractId: input.contractId,
+        features: normalizeFeatureIds(input.features),
+        hash: surfaceHash({ contractId: input.contractId, features: input.features })
+    };
+    if (input.meta !== undefined) {
+        surface.meta = input.meta;
+    }
+    return surface;
+}
+export function createContractSet(surfaces) {
+    const normalized = [...surfaces]
+        .map((surface) => surface.meta === undefined
+        ? createSurface({ contractId: surface.contractId, features: surface.features })
+        : createSurface({ contractId: surface.contractId, features: surface.features, meta: surface.meta }))
+        .sort((a, b) => a.contractId.localeCompare(b.contractId));
+    return {
+        format: "api-contract.set.v1",
+        surfaces: normalized,
+        hash: hashJson(normalized.map((surface) => [surface.contractId, surface.hash]))
+    };
+}
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEvE,MAAM,UAAU,aAAa,CAAC,KAI7B;IACC,MAAM,OAAO,GAAY;QACvB,MAAM,EAAE,yBAAyB;QACjC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC7C,IAAI,EAAE,WAAW,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;KAC9E,CAAC;IAEF,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAA2B;IAC3D,MAAM,UAAU,GAAG,CAAC,GAAG,QAAQ,CAAC;SAC7B,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS;QAC1C,CAAC,CAAC,aAAa,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC/E,CAAC,CAAC,aAAa,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;SACrG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5D,OAAO;QACL,MAAM,EAAE,qBAAqB;QAC7B,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;KAChF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+export type ContractRef<Id extends string = string, Features extends string = string> = {
+    readonly __apiContract?: {
+        readonly id: Id;
+        readonly features: Features;
+    };
+};
+export type RequiresContract<Id extends string = string, Features extends string = string> = ContractRef<Id, Features> & {
+    readonly __requiresContract?: true;
+};
+export type SupportsContract<Id extends string = string, Features extends string = string> = ContractRef<Id, Features> & {
+    readonly __supportsContract?: true;
+};
+export type ContractIdOf<T> = T extends ContractRef<infer Id, string> ? Id : never;
+export type FeaturesOf<T> = T extends ContractRef<string, infer Features> ? Features : never;
+export type MissingFeatures<Required, Supported> = Exclude<FeaturesOf<Required>, FeaturesOf<Supported>>;
+export type IsLooseFeatureSet<T> = string extends FeaturesOf<T> ? true : false;
+export type IsCompatible<Required, Supported> = IsLooseFeatureSet<Required> extends true ? boolean : IsLooseFeatureSet<Supported> extends true ? boolean : ContractIdOf<Required> extends ContractIdOf<Supported> ? MissingFeatures<Required, Supported> extends never ? true : false : false;
+export type AssertCompatible<Required, Supported> = IsCompatible<Required, Supported> extends true ? true : IsCompatible<Required, Supported> extends boolean ? true : ["Missing API contract features", MissingFeatures<Required, Supported>];
+export type Expect<T extends true> = T;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,CACrB,EAAE,SAAS,MAAM,GAAG,MAAM,EAC1B,QAAQ,SAAS,MAAM,GAAG,MAAM,IAC9B;IACF,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;QAChB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;KAC7B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,EAAE,SAAS,MAAM,GAAG,MAAM,EAC1B,QAAQ,SAAS,MAAM,GAAG,MAAM,IAC9B,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,GAAG;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,EAAE,SAAS,MAAM,GAAG,MAAM,EAC1B,QAAQ,SAAS,MAAM,GAAG,MAAM,IAC9B,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,GAAG;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,IACxB,CAAC,SAAS,WAAW,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;AAEvD,MAAM,MAAM,UAAU,CAAC,CAAC,IACtB,CAAC,SAAS,WAAW,CAAC,MAAM,EAAE,MAAM,QAAQ,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEnE,MAAM,MAAM,eAAe,CAAC,QAAQ,EAAE,SAAS,IAC7C,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B,MAAM,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAE9C,MAAM,MAAM,YAAY,CAAC,QAAQ,EAAE,SAAS,IAC1C,iBAAiB,CAAC,QAAQ,CAAC,SAAS,IAAI,GAAG,OAAO,GAClD,iBAAiB,CAAC,SAAS,CAAC,SAAS,IAAI,GAAG,OAAO,GACnD,YAAY,CAAC,QAAQ,CAAC,SAAS,YAAY,CAAC,SAAS,CAAC,GAClD,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,KAAK,GAChD,IAAI,GACJ,KAAK,GACP,KAAK,CAAC;AAEZ,MAAM,MAAM,gBAAgB,CAAC,QAAQ,EAAE,SAAS,IAC9C,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,IAAI,GAC1C,IAAI,GACJ,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,OAAO,GAC/C,IAAI,GACJ,CAAC,+BAA+B,EAAE,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAEhF,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/usage-scan.d.ts

@@ -0,0 +1,16 @@
+import type { FeatureCatalog, UsageSurface } from "./model.js";
+export declare function createUsageSurface(input: {
+    packageName: string;
+    dependencyName: string;
+    contractId: string;
+    features: Iterable<string>;
+    evidence: UsageSurface["evidence"];
+    locations?: UsageSurface["locations"];
+}): UsageSurface;
+export declare function scanUsageTarget(input: {
+    target: string;
+    packageName: string;
+    dependencyName: string;
+    catalog: FeatureCatalog;
+}): UsageSurface;
+//# sourceMappingURL=usage-scan.d.ts.map

package/dist/usage-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-scan.d.ts","sourceRoot":"","sources":["../src/usage-scan.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAiB,YAAY,EAAE,MAAM,YAAY,CAAC;AAI9E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;CACvC,GAAG,YAAY,CAQf;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG,YAAY,CAkCf"}

package/dist/usage-scan.js

@@ -0,0 +1,66 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+import { createSurface } from "./surface.js";
+const sourceExtensions = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"]);
+export function createUsageSurface(input) {
+    return {
+        packageName: input.packageName,
+        dependencyName: input.dependencyName,
+        surface: createSurface({ contractId: input.contractId, features: input.features }),
+        evidence: input.evidence,
+        ...(input.locations === undefined ? {} : { locations: input.locations })
+    };
+}
+export function scanUsageTarget(input) {
+    const featureIds = input.catalog.features.map((feature) => feature.id);
+    const usedFeatures = new Set();
+    const locations = [];
+    for (const file of listSourceFiles(input.target)) {
+        const text = readFileSync(file, "utf8");
+        const lines = text.split(/\r?\n/g);
+        for (const [index, line] of lines.entries()) {
+            const hasDependency = line.includes(input.dependencyName);
+            const lineFeatures = featureIds.filter((feature) => line.includes(feature));
+            for (const feature of lineFeatures)
+                usedFeatures.add(feature);
+            if (hasDependency || lineFeatures.length > 0) {
+                const baseLocation = { file: relative(input.target, file), line: index + 1 };
+                const importPath = hasDependency ? { importPath: input.dependencyName } : {};
+                if (lineFeatures.length === 0) {
+                    locations.push({ ...baseLocation, ...importPath });
+                }
+                else {
+                    for (const feature of lineFeatures) {
+                        locations.push({ ...baseLocation, ...importPath, feature });
+                    }
+                }
+            }
+        }
+    }
+    return createUsageSurface({
+        packageName: input.packageName,
+        dependencyName: input.dependencyName,
+        contractId: input.catalog.contractId,
+        features: usedFeatures,
+        evidence: "source-scan",
+        locations
+    });
+}
+function listSourceFiles(target) {
+    const stat = statSync(target);
+    if (stat.isFile())
+        return sourceExtensions.has(extname(target)) ? [target] : [];
+    const out = [];
+    for (const entry of readdirSync(target)) {
+        if (entry === "node_modules" || entry === "dist" || entry === ".git")
+            continue;
+        const full = join(target, entry);
+        const entryStat = statSync(full);
+        if (entryStat.isDirectory())
+            out.push(...listSourceFiles(full));
+        else if (entryStat.isFile() && sourceExtensions.has(extname(full)))
+            out.push(full);
+    }
+    return out.sort();
+}
+//# sourceMappingURL=usage-scan.js.map

package/dist/usage-scan.js.map

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

package/examples/claims/claim.json

@@ -0,0 +1,13 @@
+{
+  "subject": "npm:@async/claims-pipeline@1.0.0",
+  "claim": "requires-api-contract",
+  "surface": {
+    "format": "api-contract.surface.v1",
+    "contractId": "@async/pipeline.declaration",
+    "features": ["step.shell", "task.run"],
+    "hash": "sha256:6ed689db2412e486f7b1c57ba255d8ab244e9d1a801ebc143049449bc4b21a95"
+  },
+  "evidence": "published-manifest",
+  "issuer": "npm:@async/claims-pipeline",
+  "issuedAt": "2026-06-14T00:00:00Z"
+}

package/examples/db-ledger/API_SURFACE.md

@@ -0,0 +1,26 @@
+# @async/db API Surface Ledger
+
+This file is the generated review ledger for semantic API contract features. It is current-state contract documentation, not a changelog or tutorial.
+
+## Async DB Package Surface
+
+Contract: `@async/db.package`
+
+### Cli
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `cli.sync` | async-db sync command | public | stable | active |  |  |
+
+### Package Exports
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `export.hono` | Optional Hono integration export | beta | preview | active |  |  |
+| `export.root` | Root package export | public | stable | active |  |  |
+
+## Supported Surfaces
+
+| Contract | Hash | Features |
+| --- | --- | --- |
+| `@async/db.package` | `sha256:30ee7f5f65023461567b6de4e3bd81370207de1231e5d85c6153d4161dc43a36` | `cli.sync`, `export.hono`, `export.root` |