@dsh-enhanced/plugin-control-plane 0.1.7 → 0.1.14

package/lib/catalog.d.ts

@@ -1,9 +1,14 @@
-export interface CatalogEntry {
+export interface CatalogRegistryArtifact {
+    /** Owner-authorized registry identity that produced this immutable object. */
+    id: string;
+    /** Canonical absolute file URL for the local immutable registry root. */
+    locator: string;
+    /** Canonical absolute file URL for this package/version tarball. */
+    reference: string;
+}
+export interface CatalogEntry extends CatalogPackage {
     id: string;
     capabilities: string[];
-    package: string;
-    version: string;
-    integrity: string;
     /** Additional top-level bundles that must be installed with this candidate. */
     requires: readonly CatalogPackage[];
     authorities: string[];
@@ -13,21 +18,101 @@ export interface CatalogPackage {
     package: string;
     version: string;
     integrity: string;
+    /** Optional for compatibility with historical registry package entries. */
+    registry?: CatalogRegistryArtifact;
 }
 export interface CapabilityCatalog {
     schemaVersion: 1;
     entries: CatalogEntry[];
 }
+export interface LoadedCapabilityCatalog {
+    catalog: CapabilityCatalog;
+    digest: string;
+    provenance: 'owner-provided-integrity-pinned';
+}
+export interface CatalogAdmissionInput {
+    catalog: {
+        id: string;
+        path: string;
+    };
+    registry: {
+        id: string;
+        locator: string;
+    };
+    installationId: string;
+    operationId: string;
+    plan: {
+        id: string;
+        digest: string;
+        revision: number;
+    };
+    release: {
+        id: string;
+        fence: number;
+    };
+    expectedBeforeCatalogDigest: string;
+    expectedAfterCatalogDigest: string;
+    registryReference: string;
+    artifactStatementDigest: string;
+    artifactSignature: string;
+    verificationEvidenceDigest: string;
+    candidate: unknown;
+}
+export interface CatalogAdmissionEvidence {
+    kind: 'catalog-admission';
+    admissionId: string;
+    catalogId: string;
+    beforeCatalogDigest: string;
+    afterCatalogDigest: string;
+    registryReference: string;
+    artifactStatementDigest: string;
+    artifactSignatureDigest: string;
+    verificationEvidenceDigest: string;
+    candidate: CatalogEntry;
+}
+export interface CatalogAdmissionResult {
+    /** Exact receipt evidence. `replayed` is deliberately kept outside it. */
+    evidence: CatalogAdmissionEvidence;
+    replayed: boolean;
+}
+export interface CatalogAdmissionPreview {
+    beforeCatalogDigest: string;
+    afterCatalogDigest: string;
+    catalog: CapabilityCatalog;
+    candidate: CatalogEntry;
+}
+/** Fault-injection points for durability tests. Production callers omit this. */
+export interface CatalogAdmissionDurabilityHooks {
+    afterTemporaryFileSync?(temporaryPath: string): void | Promise<void>;
+    afterJournalSync?(journalPath: string): void | Promise<void>;
+    beforeAtomicRename?(catalogPath: string, temporaryPath: string): void | Promise<void>;
+    afterAtomicRename?(catalogPath: string): void | Promise<void>;
+}
+export declare class CatalogAdmissionError extends Error {
+    readonly code: 'conflict' | 'invalid-input' | 'unsafe-catalog';
+    constructor(code: 'conflict' | 'invalid-input' | 'unsafe-catalog', message: string);
+}
 export declare function parseCatalog(value: unknown): CapabilityCatalog;
+export declare function assertCatalogIdentity(catalog: CapabilityCatalog): void;
+/** Pure deterministic transition used while constructing the signed request. */
+export declare function previewCatalogAdmission(current: unknown, rawCandidate: unknown): CatalogAdmissionPreview;
+/** Derives the receipt identity from the complete request-bound admission. */
+export declare function catalogAdmissionId(input: CatalogAdmissionInput): string;
+/**
+ * Atomically admits one independently verified candidate into the canonical
+ * owner-private catalog. The expected digest is a request-bound CAS fence.
+ * Every writer of this owner catalog must use this helper (or honor its shared
+ * lock); POSIX rename alone cannot conditionally replace an arbitrary writer.
+ */
+export declare function admitCatalogCandidate(input: CatalogAdmissionInput, hooks?: CatalogAdmissionDurabilityHooks): Promise<CatalogAdmissionResult>;
 export declare function loadCatalog(path: string): Promise<CapabilityCatalog>;
 /**
- * Curated first-party candidates make a new core installation immediately
- * useful without granting an Agent registry, network, or activation access.
- * They deliberately remain pinned to a previously published, immutable npm
- * release.  An owner-created catalog at Config.catalogPath replaces this list.
+ * Package-local example used by documentation and tests. It is deliberately
+ * not a runtime fallback or trust source because it is not signature-verified.
+ * Runtime discovery requires an owner-provided, integrity-pinned regular file.
  */
-export declare const firstPartyCatalog: CapabilityCatalog;
-export declare function loadCatalogWithFirstPartyFallback(path: string): Promise<CapabilityCatalog>;
+export declare const exampleIntegrityPinnedCatalog: CapabilityCatalog;
+export declare function loadCatalogWithMetadata(path: string): Promise<LoadedCapabilityCatalog>;
 export declare function discover(catalog: CapabilityCatalog, capability: string): CatalogEntry[];
 export declare function candidateDigest(entry: CatalogEntry, profile: string): string;
 //# sourceMappingURL=catalog.d.ts.map

package/lib/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,+EAA+E;IAC/E,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;IACnC,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAAG,aAAa,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE;AA8ChF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAkB9D;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAI1E;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBA8E9B,CAAA;AAEF,wBAAsB,iCAAiC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAOhG;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,EAAE,CAOvF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5E"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}