@lssm/lib.contracts-spec 17.3.2

package/dist/editions/schema.d.ts

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+export declare const editionLifecycleStateSchema: z.ZodEnum<{
+    archived: "archived";
+    deprecated: "deprecated";
+    draft: "draft";
+    experiment: "experiment";
+    migration: "migration";
+    published: "published";
+    review: "review";
+    rollback: "rollback";
+}>;
+export declare const editionStorageKindSchema: z.ZodEnum<{
+    database: "database";
+    file: "file";
+}>;
+export declare const editionHybridStateSchema: z.ZodEnum<{
+    database_authoritative_conflict: "database_authoritative_conflict";
+    db_draft_to_file_patch: "db_draft_to_file_patch";
+    diverged: "diverged";
+    file_authoritative_conflict: "file_authoritative_conflict";
+    file_release_to_db_published: "file_release_to_db_published";
+    in_sync: "in_sync";
+    manual_resolution_required: "manual_resolution_required";
+    sync_failed: "sync_failed";
+    sync_resolved: "sync_resolved";
+}>;
+export declare const editionEvolutionIntentSchema: z.ZodEnum<{
+    additive: "additive";
+    behavior_compatible: "behavior_compatible";
+    breaking: "breaking";
+    experiment: "experiment";
+    migration_required: "migration_required";
+    rollback_ready: "rollback_ready";
+}>;
+export declare const editionAuthorityModeSchema: z.ZodEnum<{
+    apply_reversible: "apply_reversible";
+    autonomous_steward: "autonomous_steward";
+    draft_patch: "draft_patch";
+    human_approval_required: "human_approval_required";
+    mixed: "mixed";
+    suggest: "suggest";
+}>;
+export declare const editionKindSchema: z.ZodEnum<{
+    contract: "contract";
+    credit_note: "credit_note";
+    file: "file";
+    form: "form";
+    invoice: "invoice";
+    knowledge_doc: "knowledge_doc";
+    note: "note";
+    policy: "policy";
+    quote: "quote";
+}>;
+export declare const editionVersionSetSchema: z.ZodObject<{
+    contractVersion: z.ZodString;
+    editionVersion: z.ZodString;
+    storageRevision: z.ZodString;
+    releaseVersion: z.ZodOptional<z.ZodString>;
+    experimentVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const editionIdentitySchema: z.ZodObject<{
+    subjectKey: z.ZodString;
+    subjectType: z.ZodString;
+    editionKind: z.ZodEnum<{
+        contract: "contract";
+        credit_note: "credit_note";
+        file: "file";
+        form: "form";
+        invoice: "invoice";
+        knowledge_doc: "knowledge_doc";
+        note: "note";
+        policy: "policy";
+        quote: "quote";
+    }>;
+    editionId: z.ZodString;
+    state: z.ZodEnum<{
+        archived: "archived";
+        deprecated: "deprecated";
+        draft: "draft";
+        experiment: "experiment";
+        migration: "migration";
+        published: "published";
+        review: "review";
+        rollback: "rollback";
+    }>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+export declare const governedEditionFacetSchema: z.ZodObject<{
+    versions: z.ZodObject<{
+        contractVersion: z.ZodString;
+        editionVersion: z.ZodString;
+        storageRevision: z.ZodString;
+        releaseVersion: z.ZodOptional<z.ZodString>;
+        experimentVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    evolutionIntent: z.ZodEnum<{
+        additive: "additive";
+        behavior_compatible: "behavior_compatible";
+        breaking: "breaking";
+        experiment: "experiment";
+        migration_required: "migration_required";
+        rollback_ready: "rollback_ready";
+    }>;
+    connectVerdictRefs: z.ZodArray<z.ZodString>;
+    lineageRefs: z.ZodArray<z.ZodString>;
+    sourceRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const editionFileProjectionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    path: z.ZodString;
+    gitRef: z.ZodOptional<z.ZodString>;
+    commitSha: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    releaseCapsuleRef: z.ZodOptional<z.ZodString>;
+    multiEditionSelector: z.ZodOptional<z.ZodString>;
+    buildSelectorRef: z.ZodOptional<z.ZodString>;
+    deploySelectorRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const editionDatabaseProjectionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"database">;
+    recordRef: z.ZodString;
+    workspaceRef: z.ZodString;
+    verticalRef: z.ZodOptional<z.ZodString>;
+    customerRef: z.ZodOptional<z.ZodString>;
+    collaborationSessionRefs: z.ZodArray<z.ZodString>;
+    revisionRef: z.ZodString;
+    historyRefs: z.ZodArray<z.ZodString>;
+    rollbackRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const editionHybridProjectionSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        database_authoritative_conflict: "database_authoritative_conflict";
+        db_draft_to_file_patch: "db_draft_to_file_patch";
+        diverged: "diverged";
+        file_authoritative_conflict: "file_authoritative_conflict";
+        file_release_to_db_published: "file_release_to_db_published";
+        in_sync: "in_sync";
+        manual_resolution_required: "manual_resolution_required";
+        sync_failed: "sync_failed";
+        sync_resolved: "sync_resolved";
+    }>;
+    sourceStorage: z.ZodEnum<{
+        database: "database";
+        file: "file";
+    }>;
+    targetStorage: z.ZodEnum<{
+        database: "database";
+        file: "file";
+    }>;
+    sourceRef: z.ZodString;
+    targetRef: z.ZodString;
+    authoritativeStorage: z.ZodOptional<z.ZodEnum<{
+        database: "database";
+        file: "file";
+    }>>;
+    selectorRef: z.ZodOptional<z.ZodString>;
+    conflictReason: z.ZodOptional<z.ZodString>;
+    resolutionPolicyRef: z.ZodOptional<z.ZodString>;
+    divergenceRef: z.ZodOptional<z.ZodString>;
+    evidenceRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const editionAuthorityPolicySchema: z.ZodObject<{
+    policyRef: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        customer: "customer";
+        lifecycle_state: "lifecycle_state";
+        subject_class: "subject_class";
+        vertical: "vertical";
+        workspace: "workspace";
+    }>>;
+    storageAuthority: z.ZodEnum<{
+        database: "database";
+        file: "file";
+    }>;
+    allowedModes: z.ZodArray<z.ZodEnum<{
+        apply_reversible: "apply_reversible";
+        autonomous_steward: "autonomous_steward";
+        draft_patch: "draft_patch";
+        human_approval_required: "human_approval_required";
+        mixed: "mixed";
+        suggest: "suggest";
+    }>>;
+    requiresHumanApprovalFor: z.ZodArray<z.ZodEnum<{
+        additive: "additive";
+        behavior_compatible: "behavior_compatible";
+        breaking: "breaking";
+        experiment: "experiment";
+        migration_required: "migration_required";
+        rollback_ready: "rollback_ready";
+    }>>;
+    allowsAutonomousPromotion: z.ZodBoolean;
+    allowsAutonomousRollback: z.ZodBoolean;
+    allowsDatabaseLiveIteration: z.ZodBoolean;
+    requiresFileMaterializationForRelease: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const editionEvidenceSchema: z.ZodObject<{
+    compatibilityIntent: z.ZodEnum<{
+        additive: "additive";
+        behavior_compatible: "behavior_compatible";
+        breaking: "breaking";
+        experiment: "experiment";
+        migration_required: "migration_required";
+        rollback_ready: "rollback_ready";
+    }>;
+    connectVerdictRefs: z.ZodArray<z.ZodString>;
+    testEvidenceRefs: z.ZodArray<z.ZodString>;
+    replayEvidenceRefs: z.ZodArray<z.ZodString>;
+    rollbackEvidenceRefs: z.ZodArray<z.ZodString>;
+    promotionEvidenceRefs: z.ZodArray<z.ZodString>;
+    migrationRefs: z.ZodArray<z.ZodString>;
+    releaseRefs: z.ZodArray<z.ZodString>;
+    experimentRefs: z.ZodArray<z.ZodString>;
+    policyDecisionRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;

package/dist/editions/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";export const editionLifecycleStateSchema=e.enum(["draft","review","published","experiment","deprecated","archived","rollback","migration"]);export const editionStorageKindSchema=e.enum(["file","database"]);export const editionHybridStateSchema=e.enum(["db_draft_to_file_patch","file_release_to_db_published","in_sync","diverged","file_authoritative_conflict","database_authoritative_conflict","manual_resolution_required","sync_failed","sync_resolved"]);export const editionEvolutionIntentSchema=e.enum(["additive","behavior_compatible","breaking","experiment","migration_required","rollback_ready"]);export const editionAuthorityModeSchema=e.enum(["suggest","draft_patch","apply_reversible","autonomous_steward","human_approval_required","mixed"]);export const editionKindSchema=e.enum(["invoice","quote","credit_note","contract","file","form","note","policy","knowledge_doc"]);export const editionVersionSetSchema=e.object({contractVersion:e.string().min(1),editionVersion:e.string().min(1),storageRevision:e.string().min(1),releaseVersion:e.string().min(1).optional(),experimentVersion:e.string().min(1).optional()}).strict();export const editionIdentitySchema=e.object({subjectKey:e.string().min(1),subjectType:e.string().min(1),editionKind:editionKindSchema,editionId:e.string().min(1),state:editionLifecycleStateSchema,createdBy:e.string().min(1),createdAt:e.string().min(1)}).strict();export const governedEditionFacetSchema=e.object({versions:editionVersionSetSchema,evolutionIntent:editionEvolutionIntentSchema,connectVerdictRefs:e.array(e.string().min(1)),lineageRefs:e.array(e.string().min(1)),sourceRefs:e.array(e.string().min(1)).min(1)}).strict();export const editionFileProjectionSchema=e.object({kind:e.literal("file"),path:e.string().min(1),gitRef:e.string().min(1).optional(),commitSha:e.string().min(1).optional(),branch:e.string().min(1).optional(),tag:e.string().min(1).optional(),releaseCapsuleRef:e.string().min(1).optional(),multiEditionSelector:e.string().min(1).optional(),buildSelectorRef:e.string().min(1).optional(),deploySelectorRef:e.string().min(1).optional()}).strict();export const editionDatabaseProjectionSchema=e.object({kind:e.literal("database"),recordRef:e.string().min(1),workspaceRef:e.string().min(1),verticalRef:e.string().min(1).optional(),customerRef:e.string().min(1).optional(),collaborationSessionRefs:e.array(e.string().min(1)),revisionRef:e.string().min(1),historyRefs:e.array(e.string().min(1)).min(1),rollbackRefs:e.array(e.string().min(1)).min(1)}).strict();export const editionHybridProjectionSchema=e.object({state:editionHybridStateSchema,sourceStorage:editionStorageKindSchema,targetStorage:editionStorageKindSchema,sourceRef:e.string().min(1),targetRef:e.string().min(1),authoritativeStorage:editionStorageKindSchema.optional(),selectorRef:e.string().min(1).optional(),conflictReason:e.string().min(1).optional(),resolutionPolicyRef:e.string().min(1).optional(),divergenceRef:e.string().min(1).optional(),evidenceRefs:e.array(e.string().min(1))}).strict();export const editionAuthorityPolicySchema=e.object({policyRef:e.string().min(1),scopes:e.array(e.enum(["vertical","workspace","customer","subject_class","lifecycle_state"])).min(1),storageAuthority:editionStorageKindSchema,allowedModes:e.array(editionAuthorityModeSchema).min(1),requiresHumanApprovalFor:e.array(editionEvolutionIntentSchema),allowsAutonomousPromotion:e.boolean(),allowsAutonomousRollback:e.boolean(),allowsDatabaseLiveIteration:e.boolean(),requiresFileMaterializationForRelease:e.boolean()}).strict();export const editionEvidenceSchema=e.object({compatibilityIntent:editionEvolutionIntentSchema,connectVerdictRefs:e.array(e.string().min(1)),testEvidenceRefs:e.array(e.string().min(1)),replayEvidenceRefs:e.array(e.string().min(1)),rollbackEvidenceRefs:e.array(e.string().min(1)),promotionEvidenceRefs:e.array(e.string().min(1)),migrationRefs:e.array(e.string().min(1)),releaseRefs:e.array(e.string().min(1)),experimentRefs:e.array(e.string().min(1)),policyDecisionRefs:e.array(e.string().min(1))}).strict();

package/dist/editions/storage-file.d.ts

@@ -0,0 +1,31 @@
+import type { EditionLifecycle } from './types.js';
+export interface FileEditionPatch {
+    patchRef: string;
+    editionId: string;
+    path: string;
+    baseRef: string;
+    targetRef: string;
+    selectorRef?: string;
+    evidenceRefs: string[];
+}
+export interface FileEditionPatchInput {
+    edition: EditionLifecycle;
+    baseRef: string;
+    targetRef: string;
+    evidenceRefs: string[];
+}
+export interface FileEditionAdapter {
+    getEditionByPath(path: string, selectorRef?: string): EditionLifecycle | undefined;
+    listFileEditions(path?: string): EditionLifecycle[];
+    materializePatch(input: FileEditionPatchInput): FileEditionPatch;
+}
+export declare class InMemoryFileEditionAdapter implements FileEditionAdapter {
+    private readonly editions;
+    private readonly patches;
+    constructor(initialEditions?: EditionLifecycle[]);
+    getEditionByPath(path: string, selectorRef?: string): EditionLifecycle | undefined;
+    listFileEditions(path?: string): EditionLifecycle[];
+    materializePatch(input: FileEditionPatchInput): FileEditionPatch;
+    listPatches(): FileEditionPatch[];
+}
+export declare function createInMemoryFileEditionAdapter(initialEditions?: EditionLifecycle[]): InMemoryFileEditionAdapter;

package/dist/editions/storage-file.js

@@ -0,0 +1 @@
+export class InMemoryFileEditionAdapter{editions=new Map;patches=[];constructor(e=[]){for(const i of e){n(i);this.editions.set(r(i),structuredClone(i))}}getEditionByPath(e,i){return this.listFileEditions(e).find((t)=>t.storage.kind==="file"&&(!i||t.storage.multiEditionSelector===i))}listFileEditions(e){return Array.from(this.editions.values()).filter((i)=>i.storage.kind==="file"&&(!e||i.storage.path===e)).map((i)=>structuredClone(i))}materializePatch(e){if(e.edition.storage.kind!=="file")throw Error("FileEditionAdapter only accepts file-backed editions.");const i={patchRef:`patch:${e.edition.identity.editionId}:${this.patches.length+1}`,editionId:e.edition.identity.editionId,path:e.edition.storage.path,baseRef:e.baseRef,targetRef:e.targetRef,selectorRef:e.edition.storage.multiEditionSelector,evidenceRefs:[...e.evidenceRefs]};this.patches.push(i);return{...i,evidenceRefs:[...i.evidenceRefs]}}listPatches(){return this.patches.map((e)=>({...e,evidenceRefs:[...e.evidenceRefs]}))}}export function createInMemoryFileEditionAdapter(e=[]){return new InMemoryFileEditionAdapter(e)}function n(e){if(e.storage.kind!=="file")throw Error("FileEditionAdapter only accepts file-backed editions.")}function r(e){if(e.storage.kind!=="file")throw Error("FileEditionAdapter only accepts file-backed editions.");return`${e.storage.path}:${e.storage.multiEditionSelector??"default"}`}

package/dist/editions/storage-hybrid.d.ts

@@ -0,0 +1,42 @@
+import type { DatabaseEditionAdapter } from './storage.js';
+import type { FileEditionAdapter, FileEditionPatch } from './storage-file.js';
+import type { EditionHybridProjection, EditionLifecycle } from './types.js';
+export interface HybridEditionSyncResult {
+    hybrid: EditionHybridProjection;
+    patch?: FileEditionPatch;
+    databaseEdition?: EditionLifecycle;
+    evidenceRefs: string[];
+}
+export interface HybridEditionSyncAdapter {
+    materializeDatabaseDraftToFilePatch(input: {
+        databaseEdition: EditionLifecycle;
+        fileAdapter: FileEditionAdapter;
+        baseRef: string;
+        targetRef: string;
+        evidenceRefs: string[];
+    }): HybridEditionSyncResult;
+    projectFileReleaseToDatabase(input: {
+        fileEdition: EditionLifecycle;
+        databaseAdapter: DatabaseEditionAdapter;
+        databaseEdition: EditionLifecycle;
+        actorRef: string;
+        evidenceRefs: string[];
+    }): HybridEditionSyncResult;
+}
+export declare class InMemoryHybridEditionSyncAdapter implements HybridEditionSyncAdapter {
+    materializeDatabaseDraftToFilePatch(input: {
+        databaseEdition: EditionLifecycle;
+        fileAdapter: FileEditionAdapter;
+        baseRef: string;
+        targetRef: string;
+        evidenceRefs: string[];
+    }): HybridEditionSyncResult;
+    projectFileReleaseToDatabase(input: {
+        fileEdition: EditionLifecycle;
+        databaseAdapter: DatabaseEditionAdapter;
+        databaseEdition: EditionLifecycle;
+        actorRef: string;
+        evidenceRefs: string[];
+    }): HybridEditionSyncResult;
+}
+export declare function createInMemoryHybridEditionSyncAdapter(): InMemoryHybridEditionSyncAdapter;

package/dist/editions/storage-hybrid.js

@@ -0,0 +1 @@
+export class InMemoryHybridEditionSyncAdapter{materializeDatabaseDraftToFilePatch(e){if(e.databaseEdition.storage.kind!=="database")throw Error("Hybrid DB-to-file sync requires a database edition.");const i=a(e.databaseEdition),t=e.fileAdapter.materializePatch({edition:i,baseRef:e.baseRef,targetRef:e.targetRef,evidenceRefs:e.evidenceRefs});return{hybrid:{state:"db_draft_to_file_patch",sourceStorage:"database",targetStorage:"file",sourceRef:e.databaseEdition.storage.recordRef,targetRef:`file:${t.path}`,authoritativeStorage:"database",evidenceRefs:[...e.evidenceRefs]},patch:t,evidenceRefs:[...e.evidenceRefs]}}projectFileReleaseToDatabase(e){r(e.fileEdition,e.databaseEdition);const i=e.fileEdition.storage.kind==="file"?e.fileEdition.storage.path:"",t=e.databaseAdapter.upsertEdition({edition:e.databaseEdition,actorRef:e.actorRef,evidenceRefs:e.evidenceRefs});if(t.storage.kind!=="database")throw Error("Hybrid file-to-DB sync requires database projection.");return{hybrid:{state:"file_release_to_db_published",sourceStorage:"file",targetStorage:"database",sourceRef:`file:${i}`,targetRef:t.storage.recordRef,authoritativeStorage:"file",evidenceRefs:[...e.evidenceRefs]},databaseEdition:t,evidenceRefs:[...e.evidenceRefs]}}}export function createInMemoryHybridEditionSyncAdapter(){return new InMemoryHybridEditionSyncAdapter}function r(e,i){if(e.storage.kind!=="file")throw Error("Hybrid file-to-DB sync requires a file edition.");if(i.storage.kind!=="database")throw Error("Hybrid file-to-DB sync requires a database projection.");if(i.identity.state!=="published")throw Error("Hybrid file-to-DB sync requires a published DB projection.");if(e.identity.subjectKey!==i.identity.subjectKey)throw Error("Hybrid file-to-DB sync requires matching subject keys.");if(e.identity.subjectType!==i.identity.subjectType)throw Error("Hybrid file-to-DB sync requires matching subject types.");if(!(i.governedFacet?.lineageRefs.includes(e.identity.editionId)??!1))throw Error("Hybrid file-to-DB sync requires DB lineage to include the file release.");if(!i.evidence.releaseRefs.length)throw Error("Hybrid file-to-DB sync requires release evidence refs.");if(!i.evidence.promotionEvidenceRefs.length)throw Error("Hybrid file-to-DB sync requires promotion evidence refs.");if(!i.evidence.replayEvidenceRefs.length)throw Error("Hybrid file-to-DB sync requires replay evidence refs.")}function a(e){if(e.storage.kind!=="database")throw Error("Hybrid DB-to-file sync requires a database edition.");return{...e,storage:{kind:"file",path:e.hybrid?.targetRef.replace(/^file:/,"")??e.governedFacet?.sourceRefs[0]??e.identity.editionId,multiEditionSelector:e.hybrid?.selectorRef,buildSelectorRef:e.hybrid?.selectorRef}}}

package/dist/editions/storage-parity.d.ts

@@ -0,0 +1,16 @@
+import type { FileEditionPatch } from './storage-file.js';
+import type { EditionLifecycle } from './types.js';
+export interface EditionStorageParityInput {
+    fileEditions: EditionLifecycle[];
+    databaseEditions: EditionLifecycle[];
+    hybridPatchRefs: FileEditionPatch[];
+    releaseMaterializationRefs: string[];
+}
+export interface EditionStorageParityReport {
+    firstClass: boolean;
+    missingKinds: string[];
+    fileEditionRefs: string[];
+    databaseEditionRefs: string[];
+    hybridPatchRefs: string[];
+}
+export declare function evaluateEditionStorageParity(input: EditionStorageParityInput): EditionStorageParityReport;

package/dist/editions/storage-parity.js

@@ -0,0 +1 @@
+export function evaluateEditionStorageParity(e){const a=e.fileEditions.filter((i)=>i.storage.kind==="file").map((i)=>i.identity.editionId),n=e.databaseEditions.filter((i)=>i.storage.kind==="database").map((i)=>i.identity.editionId),s=e.hybridPatchRefs.map((i)=>i.patchRef),t=[];if(!a.length)t.push("file-edition");if(!n.length)t.push("database-edition");if(!s.length)t.push("hybrid-patch");if(!e.releaseMaterializationRefs.length)t.push("release-materialization");return{firstClass:t.length===0,missingKinds:t,fileEditionRefs:a,databaseEditionRefs:n,hybridPatchRefs:s}}

package/dist/editions/storage.d.ts

@@ -0,0 +1,49 @@
+import type { EditionLifecycle } from './types.js';
+export interface EditionRuntimeAuditEvent {
+    eventRef: string;
+    editionId: string;
+    actorRef: string;
+    kind: 'created' | 'updated' | 'rollback_anchor_recorded';
+    at: string;
+    evidenceRefs: string[];
+}
+export interface DatabaseEditionPartition {
+    workspaceRef: string;
+    verticalRef?: string;
+    customerRef?: string;
+}
+export interface DatabaseEditionWriteInput {
+    edition: EditionLifecycle;
+    actorRef: string;
+    expectedRevisionRef?: string;
+    evidenceRefs?: string[];
+}
+export interface DatabaseEditionListInput extends DatabaseEditionPartition {
+    subjectKey?: string;
+}
+export interface DatabaseEditionAdapterSnapshot {
+    editions: EditionLifecycle[];
+    auditEvents: EditionRuntimeAuditEvent[];
+}
+export interface DatabaseEditionAdapter {
+    getEdition(editionId: string): EditionLifecycle | undefined;
+    listEditions(input: DatabaseEditionListInput): EditionLifecycle[];
+    upsertEdition(input: DatabaseEditionWriteInput): EditionLifecycle;
+    appendRollbackAnchor(editionId: string, rollbackRef: string): EditionLifecycle;
+    getAuditEvents(editionId: string): EditionRuntimeAuditEvent[];
+    snapshot(): DatabaseEditionAdapterSnapshot;
+}
+export declare class InMemoryDatabaseEditionAdapter implements DatabaseEditionAdapter {
+    private readonly editions;
+    private readonly auditEvents;
+    constructor(initialEditions?: EditionLifecycle[]);
+    getEdition(editionId: string): EditionLifecycle | undefined;
+    listEditions(input: DatabaseEditionListInput): EditionLifecycle[];
+    upsertEdition(input: DatabaseEditionWriteInput): EditionLifecycle;
+    appendRollbackAnchor(editionId: string, rollbackRef: string): EditionLifecycle;
+    getAuditEvents(editionId: string): EditionRuntimeAuditEvent[];
+    snapshot(): DatabaseEditionAdapterSnapshot;
+}
+export declare function createInMemoryDatabaseEditionAdapter(initialEditions?: EditionLifecycle[]): InMemoryDatabaseEditionAdapter;
+export * from './storage-file.js';
+export * from './storage-hybrid.js';

package/dist/editions/storage.js

@@ -0,0 +1 @@
+export class InMemoryDatabaseEditionAdapter{editions=new Map;auditEvents=[];constructor(e=[]){for(const t of e){o(t);this.editions.set(t.identity.editionId,n(t))}}getEdition(e){const t=this.editions.get(e);return t?n(t):void 0}listEditions(e){return Array.from(this.editions.values()).filter((t)=>a(t,e)).filter((t)=>!e.subjectKey||t.identity.subjectKey===e.subjectKey).map(n)}upsertEdition(e){o(e.edition);const t=this.editions.get(e.edition.identity.editionId);if(t&&e.expectedRevisionRef&&t.storage.kind==="database"&&t.storage.revisionRef!==e.expectedRevisionRef)throw Error(`Edition revision conflict: expected ${e.expectedRevisionRef}, got ${t.storage.revisionRef}`);const i=n(e.edition);this.editions.set(i.identity.editionId,i);this.auditEvents.push({eventRef:`event:${i.identity.editionId}:${t?"updated":"created"}:${this.auditEvents.length+1}`,editionId:i.identity.editionId,actorRef:e.actorRef,kind:t?"updated":"created",at:i.identity.createdAt,evidenceRefs:e.evidenceRefs??i.evidence.policyDecisionRefs});return n(i)}appendRollbackAnchor(e,t){const i=this.editions.get(e);if(!i)throw Error(`Edition not found: ${e}`);if(i.storage.kind!=="database")throw Error("DatabaseEditionAdapter only accepts database-backed editions.");if(!i.storage.rollbackRefs.includes(t))i.storage.rollbackRefs=[...i.storage.rollbackRefs,t];this.auditEvents.push({eventRef:`event:${e}:rollback-anchor:${this.auditEvents.length+1}`,editionId:e,actorRef:"system:database-edition-adapter",kind:"rollback_anchor_recorded",at:i.identity.createdAt,evidenceRefs:[t]});return n(i)}getAuditEvents(e){return this.auditEvents.filter((t)=>t.editionId===e).map((t)=>({...t,evidenceRefs:[...t.evidenceRefs]}))}snapshot(){return{editions:Array.from(this.editions.values()).map(n),auditEvents:this.auditEvents.map((e)=>({...e,evidenceRefs:[...e.evidenceRefs]}))}}}export function createInMemoryDatabaseEditionAdapter(e=[]){return new InMemoryDatabaseEditionAdapter(e)}function o(e){if(e.storage.kind!=="database")throw Error("DatabaseEditionAdapter only accepts database-backed editions.")}function a(e,t){if(e.storage.kind!=="database")return!1;return e.storage.workspaceRef===t.workspaceRef&&(!t.verticalRef||e.storage.verticalRef===t.verticalRef)&&(!t.customerRef||e.storage.customerRef===t.customerRef)}function n(e){return structuredClone(e)}export*from"./storage-file.js";export*from"./storage-hybrid.js";

package/dist/editions/types.d.ts

@@ -0,0 +1,109 @@
+export type EditionLifecycleState = 'draft' | 'review' | 'published' | 'experiment' | 'deprecated' | 'archived' | 'rollback' | 'migration';
+export type EditionStorageKind = 'file' | 'database';
+export type EditionHybridState = 'db_draft_to_file_patch' | 'file_release_to_db_published' | 'in_sync' | 'diverged' | 'file_authoritative_conflict' | 'database_authoritative_conflict' | 'manual_resolution_required' | 'sync_failed' | 'sync_resolved';
+export type EditionEvolutionIntent = 'additive' | 'behavior_compatible' | 'breaking' | 'experiment' | 'migration_required' | 'rollback_ready';
+export type EditionAuthorityMode = 'suggest' | 'draft_patch' | 'apply_reversible' | 'autonomous_steward' | 'human_approval_required' | 'mixed';
+export type EditionAuthorityScope = 'vertical' | 'workspace' | 'customer' | 'subject_class' | 'lifecycle_state';
+export type EditionKind = 'invoice' | 'quote' | 'credit_note' | 'contract' | 'file' | 'form' | 'note' | 'policy' | 'knowledge_doc';
+export interface EditionVersionSet {
+    contractVersion: string;
+    editionVersion: string;
+    storageRevision: string;
+    releaseVersion?: string;
+    experimentVersion?: string;
+}
+export interface EditionIdentity {
+    subjectKey: string;
+    subjectType: string;
+    editionKind: EditionKind;
+    editionId: string;
+    state: EditionLifecycleState;
+    createdBy: string;
+    createdAt: string;
+}
+export interface GovernedEditionFacet {
+    versions: EditionVersionSet;
+    evolutionIntent: EditionEvolutionIntent;
+    connectVerdictRefs: string[];
+    lineageRefs: string[];
+    sourceRefs: string[];
+}
+export interface EditionFileProjection {
+    kind: 'file';
+    path: string;
+    gitRef?: string;
+    commitSha?: string;
+    branch?: string;
+    tag?: string;
+    releaseCapsuleRef?: string;
+    multiEditionSelector?: string;
+    buildSelectorRef?: string;
+    deploySelectorRef?: string;
+}
+export interface EditionDatabaseProjection {
+    kind: 'database';
+    recordRef: string;
+    workspaceRef: string;
+    verticalRef?: string;
+    customerRef?: string;
+    collaborationSessionRefs: string[];
+    revisionRef: string;
+    historyRefs: string[];
+    rollbackRefs: string[];
+}
+export interface EditionHybridProjection {
+    state: EditionHybridState;
+    sourceStorage: EditionStorageKind;
+    targetStorage: EditionStorageKind;
+    sourceRef: string;
+    targetRef: string;
+    authoritativeStorage?: EditionStorageKind;
+    selectorRef?: string;
+    conflictReason?: string;
+    resolutionPolicyRef?: string;
+    divergenceRef?: string;
+    evidenceRefs: string[];
+}
+export interface EditionAuthorityPolicy {
+    policyRef: string;
+    scopes: EditionAuthorityScope[];
+    storageAuthority: EditionStorageKind;
+    allowedModes: EditionAuthorityMode[];
+    requiresHumanApprovalFor: EditionEvolutionIntent[];
+    allowsAutonomousPromotion: boolean;
+    allowsAutonomousRollback: boolean;
+    allowsDatabaseLiveIteration: boolean;
+    requiresFileMaterializationForRelease: boolean;
+}
+export interface EditionEvidence {
+    compatibilityIntent: EditionEvolutionIntent;
+    connectVerdictRefs: string[];
+    testEvidenceRefs: string[];
+    replayEvidenceRefs: string[];
+    rollbackEvidenceRefs: string[];
+    promotionEvidenceRefs: string[];
+    migrationRefs: string[];
+    releaseRefs: string[];
+    experimentRefs: string[];
+    policyDecisionRefs: string[];
+}
+export interface EditionLifecycle {
+    identity: EditionIdentity;
+    governedFacet?: GovernedEditionFacet;
+    storage: EditionFileProjection | EditionDatabaseProjection;
+    hybrid?: EditionHybridProjection;
+    authority: EditionAuthorityPolicy;
+    evidence: EditionEvidence;
+}
+export interface EditionValidationIssue {
+    path: (string | number)[];
+    message: string;
+}
+export type EditionValidationResult<T> = {
+    valid: true;
+    value: T;
+    issues: [];
+} | {
+    valid: false;
+    issues: EditionValidationIssue[];
+};

package/dist/editions/validation.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import type { EditionLifecycle, EditionValidationResult } from './types.js';
+export { editionAuthorityModeSchema, editionAuthorityPolicySchema, editionDatabaseProjectionSchema, editionEvidenceSchema, editionEvolutionIntentSchema, editionFileProjectionSchema, editionHybridProjectionSchema, editionHybridStateSchema, editionIdentitySchema, editionKindSchema, editionLifecycleStateSchema, editionStorageKindSchema, editionVersionSetSchema, governedEditionFacetSchema, } from './schema.js';
+export declare const editionLifecycleSchema: z.ZodType<EditionLifecycle>;
+export declare function validateEditionLifecycle(input: unknown): EditionValidationResult<EditionLifecycle>;

package/dist/editions/validation.js

@@ -0,0 +1 @@
+import{z as t}from"zod";import{editionAuthorityPolicySchema as n,editionDatabaseProjectionSchema as d,editionEvidenceSchema as c,editionFileProjectionSchema as u,editionHybridProjectionSchema as m,editionIdentitySchema as f,governedEditionFacetSchema as l}from"./schema.js";export{editionAuthorityModeSchema,editionAuthorityPolicySchema,editionDatabaseProjectionSchema,editionEvidenceSchema,editionEvolutionIntentSchema,editionFileProjectionSchema,editionHybridProjectionSchema,editionHybridStateSchema,editionIdentitySchema,editionKindSchema,editionLifecycleStateSchema,editionStorageKindSchema,editionVersionSetSchema,governedEditionFacetSchema}from"./schema.js";export const editionLifecycleSchema=t.object({identity:f,governedFacet:l.optional(),storage:t.union([u,d]),hybrid:m.optional(),authority:n,evidence:c}).strict().superRefine((e,i)=>{if(r(e.identity.editionKind)&&!e.governedFacet)i.addIssue({code:t.ZodIssueCode.custom,message:"governed edition kinds require governedFacet",path:["governedFacet"]});if(!r(e.identity.editionKind)&&e.governedFacet)i.addIssue({code:t.ZodIssueCode.custom,message:"inert edition kinds must not carry governedFacet",path:["governedFacet"]});if(e.identity.state==="published")s(i,[["connectVerdictRefs",e.evidence.connectVerdictRefs],["testEvidenceRefs",e.evidence.testEvidenceRefs],["replayEvidenceRefs",e.evidence.replayEvidenceRefs],["rollbackEvidenceRefs",e.evidence.rollbackEvidenceRefs],["promotionEvidenceRefs",e.evidence.promotionEvidenceRefs],["policyDecisionRefs",e.evidence.policyDecisionRefs]]);if(e.evidence.compatibilityIntent==="breaking"||e.evidence.compatibilityIntent==="migration_required")s(i,[["migrationRefs",e.evidence.migrationRefs]]);if(e.identity.state==="experiment"){s(i,[["experimentRefs",e.evidence.experimentRefs]]);if(!e.governedFacet?.versions.experimentVersion)i.addIssue({code:t.ZodIssueCode.custom,message:"experiment editions require experimentVersion",path:["governedFacet","versions","experimentVersion"]})}if(e.storage.kind==="file"){if(!Boolean(e.storage.gitRef??e.storage.commitSha??e.storage.branch??e.storage.tag)&&!e.storage.multiEditionSelector)i.addIssue({code:t.ZodIssueCode.custom,message:"file storage requires a Git ref or same-file multi-edition selector",path:["storage"]});if(e.storage.multiEditionSelector&&!e.storage.buildSelectorRef)i.addIssue({code:t.ZodIssueCode.custom,message:"same-file multi-edition storage requires build selector metadata",path:["storage","buildSelectorRef"]})}if(e.storage.kind==="database"){if(!e.storage.historyRefs.length||!e.storage.rollbackRefs.length)i.addIssue({code:t.ZodIssueCode.custom,message:"database-backed mutable editions require history and rollback refs",path:["storage"]})}if(e.hybrid){if(e.hybrid.sourceStorage===e.hybrid.targetStorage)i.addIssue({code:t.ZodIssueCode.custom,message:"hybrid sync must bridge different storage kinds",path:["hybrid"]});if(!e.hybrid.evidenceRefs.length)i.addIssue({code:t.ZodIssueCode.custom,message:"hybrid sync states require evidence refs",path:["hybrid","evidenceRefs"]})}if(e.authority.allowsAutonomousPromotion&&e.authority.requiresHumanApprovalFor.includes(e.evidence.compatibilityIntent))i.addIssue({code:t.ZodIssueCode.custom,message:"autonomous promotion conflicts with human approval policy for this evolution intent",path:["authority","allowsAutonomousPromotion"]})});function r(e){return["contract","invoice","quote","credit_note"].includes(e)}function s(e,i){for(const[o,a]of i)if(!a.length)e.addIssue({code:t.ZodIssueCode.custom,message:`${o} are required for this edition lifecycle state`,path:["evidence",o]})}function h(e){return e.issues.map((i)=>({path:i.path.filter((o)=>typeof o==="string"||typeof o==="number"),message:i.message}))}export function validateEditionLifecycle(e){const i=editionLifecycleSchema.safeParse(e);if(!i.success)return{valid:!1,issues:h(i.error)};return{valid:!0,value:i.data,issues:[]}}

package/dist/entities/compatibility.d.ts

@@ -0,0 +1,55 @@
+import type { DocBlock } from '../docs/types.js';
+export type ContractEntityOntologyCompatibilityIntent = 'additive' | 'root-barrel-only' | 'subpath-additive';
+export type ContractEntityOntologyPublicSurfaceKind = 'ontology-contract' | 'root-barrel-export' | 'package-subpath';
+export interface ContractEntityOntologyCompatibilityLedgerEntry {
+    id: string;
+    kind: ContractEntityOntologyPublicSurfaceKind;
+    packageName: '@lssm/lib.contracts-spec';
+    importPath: string;
+    sourcePath: string;
+    symbols: readonly string[];
+    compatibilityIntent: ContractEntityOntologyCompatibilityIntent;
+    decision: string;
+    evidenceRefs: readonly string[];
+}
+/**
+ * Compatibility ledger for the ContractSpec entity ontology public surface.
+ *
+ * The entity ontology is intentionally exposed through the package root barrel
+ * and the narrow \`./entities\` package subpath. The subpath entry is recorded
+ * explicitly so release/docs work can keep package exports, published exports,
+ * tests, and compatibility notes synchronized.
+ */
+export declare const contractEntityOntologyCompatibilityLedger: readonly [{
+    readonly id: 'contracts-spec-entity-ontology-contracts';
+    readonly kind: 'ontology-contract';
+    readonly packageName: '@lssm/lib.contracts-spec';
+    readonly importPath: '@lssm/lib.contracts-spec';
+    readonly sourcePath: 'packages/libs/contracts-spec/src/entities/index.ts';
+    readonly symbols: readonly ["defineContractEntity", "defineContractEdge", "EntityRegistry", "ContractEntitySpec", "ContractEdgeSpec", "EdgeSpec"];
+    readonly compatibilityIntent: 'additive';
+    readonly decision: 'Entity ontology contracts are additive primitives layered on existing schema contracts.';
+    readonly evidenceRefs: readonly ["packages/libs/contracts-spec/src/entities/defineContractEntity.test.ts", "packages/libs/contracts-spec/src/entities/compatibility.test.ts"];
+}, {
+    readonly id: 'contracts-spec-entity-root-barrel-export';
+    readonly kind: 'root-barrel-export';
+    readonly packageName: '@lssm/lib.contracts-spec';
+    readonly importPath: '@lssm/lib.contracts-spec';
+    readonly sourcePath: 'packages/libs/contracts-spec/src/index.ts';
+    readonly symbols: readonly ["defineContractEntity", "defineContractEdge", "EntityRegistry", "ContractEntitySpec", "ContractEdgeSpec", "EdgeSpec"];
+    readonly compatibilityIntent: 'root-barrel-only';
+    readonly decision: 'Entity ontology symbols are public from the root barrel; the entities subpath ledger entry records the narrow additive package subpath separately.';
+    readonly evidenceRefs: readonly ["packages/libs/contracts-spec/src/index.ts", "packages/libs/contracts-spec/src/entities/compatibility.test.ts"];
+}, {
+    readonly id: 'contracts-spec-entities-subpath-export';
+    readonly kind: 'package-subpath';
+    readonly packageName: '@lssm/lib.contracts-spec';
+    readonly importPath: '@lssm/lib.contracts-spec/entities';
+    readonly sourcePath: 'packages/libs/contracts-spec/package.json';
+    readonly symbols: readonly [];
+    readonly compatibilityIntent: 'subpath-additive';
+    readonly decision: 'The `./entities` package export is intentionally additive and mirrors the entity ontology symbols available from the root barrel.';
+    readonly evidenceRefs: readonly ["packages/libs/contracts-spec/package.json", "packages/libs/contracts-spec/src/entities/compatibility.test.ts"];
+}];
+export declare function assertContractEntityOntologyCompatibilityLedger(ledger?: readonly ContractEntityOntologyCompatibilityLedgerEntry[]): readonly ContractEntityOntologyCompatibilityLedgerEntry[];
+export declare const tech_contracts_entities_compatibility_DocBlocks: DocBlock[];

package/dist/entities/compatibility.js

@@ -0,0 +1,20 @@
+const o=["defineContractEntity","defineContractEdge","EntityRegistry","ContractEntitySpec","ContractEdgeSpec","EdgeSpec"];export const contractEntityOntologyCompatibilityLedger=[{id:"contracts-spec-entity-ontology-contracts",kind:"ontology-contract",packageName:"@lssm/lib.contracts-spec",importPath:"@lssm/lib.contracts-spec",sourcePath:"packages/libs/contracts-spec/src/entities/index.ts",symbols:o,compatibilityIntent:"additive",decision:"Entity ontology contracts are additive primitives layered on existing schema contracts.",evidenceRefs:["packages/libs/contracts-spec/src/entities/defineContractEntity.test.ts","packages/libs/contracts-spec/src/entities/compatibility.test.ts"]},{id:"contracts-spec-entity-root-barrel-export",kind:"root-barrel-export",packageName:"@lssm/lib.contracts-spec",importPath:"@lssm/lib.contracts-spec",sourcePath:"packages/libs/contracts-spec/src/index.ts",symbols:o,compatibilityIntent:"root-barrel-only",decision:"Entity ontology symbols are public from the root barrel; the entities subpath ledger entry records the narrow additive package subpath separately.",evidenceRefs:["packages/libs/contracts-spec/src/index.ts","packages/libs/contracts-spec/src/entities/compatibility.test.ts"]},{id:"contracts-spec-entities-subpath-export",kind:"package-subpath",packageName:"@lssm/lib.contracts-spec",importPath:"@lssm/lib.contracts-spec/entities",sourcePath:"packages/libs/contracts-spec/package.json",symbols:[],compatibilityIntent:"subpath-additive",decision:"The `./entities` package export is intentionally additive and mirrors the entity ontology symbols available from the root barrel.",evidenceRefs:["packages/libs/contracts-spec/package.json","packages/libs/contracts-spec/src/entities/compatibility.test.ts"]}];export function assertContractEntityOntologyCompatibilityLedger(e=contractEntityOntologyCompatibilityLedger){if(e.length===0)throw Error("Contract entity ontology compatibility ledger is empty.");const i=new Set;for(const t of e){if(i.has(t.id))throw Error(`Duplicate contract entity ontology compatibility ledger id: ${t.id}`);i.add(t.id);if(!t.importPath||!t.sourcePath)throw Error(`Contract entity ontology compatibility ledger entry ${t.id} is missing import or source path.`);if(t.evidenceRefs.length===0)throw Error(`Contract entity ontology compatibility ledger entry ${t.id} has no evidence refs.`)}return e}export const tech_contracts_entities_compatibility_DocBlocks=[{id:"docs.tech.contracts.entities.compatibility",title:"Contract Entity Ontology Compatibility Ledger",summary:"Entity ontology symbols are additive from the root barrel and the narrow `./entities` package subpath.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/entities/compatibility",tags:["tech","contracts","entities","compatibility","exports"],body:`# Contract Entity Ontology Compatibility Ledger
+
+The entity ontology public surface is intentionally additive through the root barrel and the narrow \`./entities\` package subpath.
+
+## Public import
+
+\`\`\`ts
+import {
+  defineContractEntity,
+  defineContractEdge,
+  EntityRegistry,
+} from '@lssm/lib.contracts-spec/entities';
+\`\`\`
+
+## Compatibility decision
+
+- \`@lssm/lib.contracts-spec\` exports the entity ontology symbols from the root barrel.
+- \`@lssm/lib.contracts-spec/entities\` is not introduced by this ledger.
+- Future work that adds \`./entities\` must update \`package.json\`, the publish exports, tests, docs, and release metadata together.
+`}];