@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/models/ConsentFlowContract.ts

@@ -14,16 +14,27 @@ export type ConsentFlowRelationships = {
         { signingAuthorityEndpoint: string; signingAuthorityName: string; issuer?: string }
     >;
     canWrite: ModelRelatedNodesI<typeof Profile, ProfileInstance>;
+    sharesDataWith: ModelRelatedNodesI<typeof Profile, ProfileInstance>;
     relatedTo: ModelRelatedNodesI<typeof Boost, BoostInstance>;
     requestedFor: ModelRelatedNodesI<
         typeof Profile,
         ProfileInstance,
         {
-            status: 'pending' | 'accepted' | 'denied';
+            status: 'pending' | 'accepted' | 'denied' | 'cancelled';
+            requestId?: string;
+            requestedBy?: string;
+            externalReferenceId?: string;
+            message?: string;
+            requestedAt?: string;
             readStatus?: 'unseen' | 'seen' | null;
         },
         {
-            status: 'pending' | 'accepted' | 'denied';
+            status: 'pending' | 'accepted' | 'denied' | 'cancelled';
+            requestId?: string;
+            requestedBy?: string;
+            externalReferenceId?: string;
+            message?: string;
+            requestedAt?: string;
             readStatus?: 'unseen' | 'seen' | null;
         }
     >;
@@ -47,6 +58,8 @@ export const ConsentFlowContract = ModelFactory<FlatDbContractType, ConsentFlowR
             createdAt: { type: 'string', required: true },
             updatedAt: { type: 'string', required: true },
             expiresAt: { type: 'string', required: false },
+            audienceVersion: { type: 'number', required: false },
+            hasConsented: { type: 'boolean', required: false },
         } as any,
         relationships: {
             createdBy: { model: Profile, direction: 'out', name: 'CREATED_BY' },
@@ -70,17 +83,35 @@ export const ConsentFlowContract = ModelFactory<FlatDbContractType, ConsentFlowR
                 },
             },
             canWrite: { model: Profile, direction: 'out', name: 'CAN_WRITE' },
+            sharesDataWith: { model: Profile, direction: 'out', name: 'SHARES_DATA_WITH' },
             relatedTo: { model: Boost, direction: 'out', name: 'RELATED_TO' },
             requestedFor: {
                 model: Profile,
                 direction: 'out',
                 name: 'REQUESTED_FOR',
                 properties: {
+                    requestId: {
+                        property: 'requestId',
+                        schema: { type: 'string', required: false },
+                    },
+                    requestedBy: {
+                        property: 'requestedBy',
+                        schema: { type: 'string', required: false },
+                    },
+                    externalReferenceId: {
+                        property: 'externalReferenceId',
+                        schema: { type: 'string', required: false },
+                    },
+                    message: { property: 'message', schema: { type: 'string', required: false } },
+                    requestedAt: {
+                        property: 'requestedAt',
+                        schema: { type: 'string', required: false },
+                    },
                     status: {
                         property: 'status',
                         schema: {
                             type: 'string',
-                            enum: ['pending', 'accepted', 'denied'],
+                            enum: ['pending', 'accepted', 'denied', 'cancelled'],
                             required: false,
                         },
                     },

package/src/models/ConsentFlowTerms.ts

@@ -19,10 +19,20 @@ export const ConsentFlowTerms = ModelFactory<FlatDbTermsType, ConsentFlowTermsRe
     {
         label: 'ConsentFlowTerms',
         schema: {
+            smartResumeFingerprint: { type: 'string', required: false },
+            smartResumePublicationStatus: { type: 'string', required: false },
+            smartResumeLeaseId: { type: 'string', required: false },
+            smartResumeLeaseUntil: { type: 'number', required: false },
+            smartResumeMutationVersion: { type: 'number', required: false },
+            smartResumeRedirectUrl: { type: 'string', required: false },
             id: { type: 'string', required: true },
+            'referral.requestId': { type: 'string', required: false },
+            'referral.requestedBy': { type: 'string', required: false },
+            'referral.externalReferenceId': { type: 'string', required: false },
             status: { type: 'string', required: true },
             createdAt: { type: 'string', required: false },
             updatedAt: { type: 'string', required: false },
+            mutationVersion: { type: 'number', required: false },
             expiresAt: { type: 'string', required: false },
             oneTime: { type: 'boolean', required: false },
             deniedWriters: { type: 'string[]', required: false },

package/src/models/ConsentFlowTransaction.ts

@@ -21,6 +21,9 @@ export const ConsentFlowTransaction = ModelFactory<
         label: 'ConsentFlowTransaction',
         schema: {
             id: { type: 'string', required: true },
+            'referral.requestId': { type: 'string', required: false },
+            'referral.requestedBy': { type: 'string', required: false },
+            'referral.externalReferenceId': { type: 'string', required: false },
             status: { type: 'string', required: true },
             expiresAt: { type: 'string', required: false },
             oneTime: { type: 'boolean', required: false },

package/src/models/Integration.ts

@@ -3,11 +3,13 @@ import { ModelFactory, ModelRelatedNodesI, NeogmaInstance } from 'neogma';
 import { neogma } from '@instance';
 
 import { Profile, ProfileInstance } from './Profile';
+import type { AppManifestVersion, AppManifestVersionInstance } from './AppManifestVersion';
 import { FlatIntegrationType } from 'types/integration';
 
 export type IntegrationRelationships = {
     createdBy: ModelRelatedNodesI<typeof Profile, ProfileInstance>;
     publishesListing: ModelRelatedNodesI<any, any>;
+    hasManifestVersion: ModelRelatedNodesI<typeof AppManifestVersion, AppManifestVersionInstance>;
 };
 
 export type IntegrationInstance = NeogmaInstance<FlatIntegrationType, IntegrationRelationships>;

package/src/models/Presentation.ts

@@ -9,8 +9,8 @@ export type PresentationRelationships = {
     presentationReceived: ModelRelatedNodesI<
         { createOne: (typeof Profile)['createOne'] },
         ProfileInstance,
-        { from: string; date: string },
-        { from: string; date: string }
+        { from: string; date: string; metadata?: Record<string, unknown> },
+        { from: string; date: string; metadata?: Record<string, unknown> }
     >;
 };
 

package/src/models/Profile.ts

@@ -75,8 +75,8 @@ export type ProfileRelationships = {
     presentationSent: ModelRelatedNodesI<
         typeof Presentation,
         PresentationInstance,
-        { to: string; date: string },
-        { to: string; date: string }
+        { to: string; date: string; metadata?: Record<string, unknown> },
+        { to: string; date: string; metadata?: Record<string, unknown> }
     >;
     usesSigningAuthority: ModelRelatedNodesI<
         typeof SigningAuthority,
@@ -238,6 +238,7 @@ export const Profile: any = ModelFactory<FlatProfileType, ProfileRelationships>(
                 properties: {
                     to: { property: 'to', schema: { type: 'string', required: true } },
                     date: { property: 'date', schema: { type: 'string', required: true } },
+                    metadata: { property: 'metadata', schema: { type: 'object', required: false } },
                 },
             },
             usesSigningAuthority: {

package/src/models/ShareLink.ts

@@ -0,0 +1,134 @@
+import { ModelFactory, NeogmaInstance } from 'neogma';
+
+import { neogma } from '@instance';
+
+/** Lifecycle status of a share. Only `active` is ever served to a recipient. */
+export type ShareLinkStatus = 'pending' | 'active' | 'stopped';
+
+/**
+ * Whether the visible content pointer for a share is committed.
+ *
+ * `staging` means a reservation exists but the object is not visible yet;
+ * `content_missing` means Brain believes content should be visible but LearnCloud
+ * does not have it, so the share fails closed and is never served.
+ */
+export type ShareContentState = 'staging' | 'finalized' | 'content_missing';
+
+/**
+ * Persisted ShareLink metadata (LC-2187).
+ *
+ * This node is the only Brain-side source of truth for the *visible* content
+ * pointer. It stores an opaque immutable `activeObjectRef` plus content/recovery
+ * hashes and byte counts — never ciphertext, a raw private source URI or a key.
+ * The concrete encrypted envelope and owner recovery JWE live together in the
+ * dedicated LearnCloud collection keyed by the immutable object reference.
+ *
+ * `version` is the committed record revision used for optimistic concurrency; a
+ * reservation (`staging`) does not change it. `contentVersion` is the visible
+ * content revision and changes only when a replacement is finalized.
+ */
+export type ShareLinkRecord = {
+    id: string;
+    namespace: string;
+    ownerProfileId: string;
+    version: number;
+    contentVersion: number;
+    attachmentId?: string | null;
+    attachmentChunkCount?: number | null;
+    /**
+     * Monotonic fence. Bumped on every reservation and on revoke; a worker may
+     * only finalize the reservation whose generation still equals this value.
+     */
+    generation: number;
+    status: ShareLinkStatus;
+    contentState: ShareContentState;
+    activeObjectRef: string | null;
+    activeObjectOperationId: string | null;
+    activeContentHash: string | null;
+    activeContentBytes: number | null;
+    activeRecoveryHash: string | null;
+    /** Operation binding: the operation id that produced the visible revision. */
+    lastOperationId: string | null;
+    /** Operation binding: the create request that first bound this share id. */
+    createdByClientRequestId: string | null;
+    title: string;
+    note: string | null;
+    selectedCount: number;
+    expiresAt: string | null;
+    stoppedAt: string | null;
+    viewCount: number;
+    lastViewedAt: string | null;
+    /** Argon2id PHC string. Plaintext passcodes are never persisted. */
+    passcodeHash?: string | null;
+    notifyOnView?: boolean;
+    minorPolicyIsMinor: boolean | null;
+    minorPolicyResolved: boolean;
+    minorPolicyDefaultExpiryDays: number;
+    minorPolicyViewCountingEnabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+
+/** Neo4j omits null properties; the repository maps missing values back to null. */
+type ShareLinkProperties = { lockTick?: number } & {
+    [Key in keyof ShareLinkRecord]:
+        | Exclude<ShareLinkRecord[Key], null>
+        | (null extends ShareLinkRecord[Key] ? undefined : never);
+};
+export type ShareLinkInstance = NeogmaInstance<ShareLinkProperties, Record<string, never>>;
+
+/**
+ * `:ShareLink` model registration. The repository writes this label with raw
+ * parameterized Cypher so it can hold the share write lock across read + write
+ * within one transaction; the model exists for schema/typed instance support and
+ * constraint registration.
+ */
+export const ShareLink = ModelFactory<ShareLinkProperties, Record<string, never>>(
+    {
+        label: 'ShareLink',
+        schema: {
+            id: { type: 'string', required: true },
+            namespace: { type: 'string', required: true },
+            ownerProfileId: { type: 'string', required: true },
+            version: { type: 'number', required: true },
+            contentVersion: { type: 'number', required: true },
+            attachmentId: { type: 'string', required: false },
+            attachmentChunkCount: { type: 'number', required: false },
+            generation: { type: 'number', required: true },
+            status: { type: 'string', required: true, enum: ['pending', 'active', 'stopped'] },
+            contentState: {
+                type: 'string',
+                required: true,
+                enum: ['staging', 'finalized', 'content_missing'],
+            },
+            activeObjectRef: { type: 'string', required: false },
+            activeObjectOperationId: { type: 'string', required: false },
+            activeContentHash: { type: 'string', required: false },
+            activeContentBytes: { type: 'number', required: false },
+            activeRecoveryHash: { type: 'string', required: false },
+            lastOperationId: { type: 'string', required: false },
+            createdByClientRequestId: { type: 'string', required: false },
+            title: { type: 'string', required: true },
+            note: { type: 'string', required: false },
+            selectedCount: { type: 'number', required: true },
+            expiresAt: { type: 'string', required: false },
+            stoppedAt: { type: 'string', required: false },
+            viewCount: { type: 'number', required: true },
+            lastViewedAt: { type: 'string', required: false },
+            passcodeHash: { type: 'string', required: false },
+            // LC-2187 records created before opt-in alerts may omit this field.
+            notifyOnView: { type: 'boolean', required: false },
+            minorPolicyIsMinor: { type: 'boolean', required: false },
+            minorPolicyResolved: { type: 'boolean', required: true },
+            minorPolicyDefaultExpiryDays: { type: 'number', required: true },
+            minorPolicyViewCountingEnabled: { type: 'boolean', required: true },
+            createdAt: { type: 'string', required: true },
+            updatedAt: { type: 'string', required: true },
+            lockTick: { type: 'number', required: false },
+        },
+        primaryKeyField: 'id',
+    },
+    neogma
+);
+
+export default ShareLink;

package/src/models/ShareViewReceipt.ts

@@ -0,0 +1,69 @@
+import { ModelFactory, NeogmaInstance } from 'neogma';
+
+import { neogma } from '@instance';
+
+/**
+ * Persisted, short-lived view receipt (LC-2187 ADR-10).
+ *
+ * Only the hash of the opaque CSPRNG token is stored — never the token, a viewer
+ * identity, an IP, a fingerprint, a credential, a key or any request body. The
+ * node is bound to one immutable committed tuple
+ * `(namespace, ownerProfileId, shareId, contentVersion, objectRef, operationId)`
+ * so a receipt for a superseded revision can never count toward the current one.
+ *
+ * `consumedAt` is the single-use marker; `lockTick` exists only so a transaction
+ * can take a write lock on the receipt AFTER it holds the share write lock.
+ * `expiresAt` bounds retention and is indexed for one-shot pruning.
+ */
+export type ShareViewReceiptRecord = {
+    receiptHash: string;
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectRef: string;
+    operationId: string;
+    createdAt: string;
+    expiresAt: string;
+    consumedAt: string | null;
+};
+
+type ShareViewReceiptProperties = { lockTick?: number } & {
+    [Key in keyof ShareViewReceiptRecord]:
+        | Exclude<ShareViewReceiptRecord[Key], null>
+        | (null extends ShareViewReceiptRecord[Key] ? undefined : never);
+};
+
+export type ShareViewReceiptInstance = NeogmaInstance<
+    ShareViewReceiptProperties,
+    Record<string, never>
+>;
+
+/**
+ * `:ShareViewReceipt` model registration. The repository writes this label with
+ * raw parameterized Cypher so consume + increment happen in one transaction with
+ * explicit share-then-receipt lock ordering; the model exists for schema and
+ * constraint registration.
+ */
+export const ShareViewReceipt = ModelFactory<ShareViewReceiptProperties, Record<string, never>>(
+    {
+        label: 'ShareViewReceipt',
+        schema: {
+            receiptHash: { type: 'string', required: true },
+            namespace: { type: 'string', required: true },
+            ownerProfileId: { type: 'string', required: true },
+            shareId: { type: 'string', required: true },
+            contentVersion: { type: 'number', required: true },
+            objectRef: { type: 'string', required: true },
+            operationId: { type: 'string', required: true },
+            createdAt: { type: 'string', required: true },
+            expiresAt: { type: 'string', required: true },
+            consumedAt: { type: 'string', required: false },
+            lockTick: { type: 'number', required: false },
+        },
+        primaryKeyField: 'receiptHash',
+    },
+    neogma
+);
+
+export default ShareViewReceipt;

package/src/models/index.ts

@@ -1,5 +1,6 @@
 import { environment } from '@environment';
 import { neogma } from '@instance';
+import { contractEventMaintenanceSchema } from '@helpers/contract-event-maintenance.helpers';
 
 import { Boost } from './Boost';
 import { Profile } from './Profile';
@@ -11,6 +12,7 @@ import { Skill } from './Skill';
 import { Tag } from './Tag';
 import { AppStoreListing } from './AppStoreListing';
 import { Integration } from './Integration';
+import { AppManifestVersion } from './AppManifestVersion';
 import { CredentialActivity } from './CredentialActivity';
 import { CredentialRefresh } from './CredentialRefresh';
 import { StatusList } from './StatusList';
@@ -69,6 +71,7 @@ Presentation.addRelationships({
         properties: {
             from: { property: 'from', schema: { type: 'string', required: true } },
             date: { property: 'date', schema: { type: 'string', required: true } },
+            metadata: { property: 'metadata', schema: { type: 'object', required: false } },
         },
     },
 });
@@ -91,6 +94,19 @@ Integration.addRelationships({
         direction: 'out',
         name: 'PUBLISHES_LISTING',
     },
+    hasManifestVersion: {
+        model: AppManifestVersion,
+        direction: 'out',
+        name: 'HAS_MANIFEST_VERSION',
+    },
+});
+
+AppStoreListing.addRelationships({
+    usesManifestVersion: {
+        model: AppManifestVersion,
+        direction: 'out',
+        name: 'USES_MANIFEST_VERSION',
+    },
 });
 
 Profile.addRelationships({
@@ -127,6 +143,9 @@ const shouldCreateIndices =
     environment.NODE_ENV === 'production' || !environment.NEO4J_SKIP_INDICES;
 
 const indexQueries = [
+    'CREATE CONSTRAINT consent_event_id IF NOT EXISTS FOR (e:ConsentFlowEvent) REQUIRE e.id IS UNIQUE',
+    'CREATE CONSTRAINT consent_delivery_id IF NOT EXISTS FOR (d:ConsentFlowEventDelivery) REQUIRE d.id IS UNIQUE',
+    ...contractEventMaintenanceSchema,
     'CREATE INDEX profileId_idx IF NOT EXISTS FOR (p:Profile) ON (p.profileId)',
     'CREATE INDEX profile_did_idx IF NOT EXISTS FOR (p:Profile) ON (p.did)',
     'CREATE TEXT INDEX profileId_text_idx IF NOT EXISTS FOR (n:Profile) ON (n.profileId)',
@@ -151,6 +170,10 @@ const indexQueries = [
     'CREATE INDEX claim_hook_updated_idx IF NOT EXISTS FOR (c:ClaimHook) ON (c.updatedAt)',
     'CREATE INDEX integration_id_idx IF NOT EXISTS FOR (i:Integration) ON (i.id)',
     'CREATE INDEX integration_publishablekey_idx IF NOT EXISTS FOR (i:Integration) ON (i.publishableKey)',
+    'CREATE INDEX app_manifest_version_id_idx IF NOT EXISTS FOR (m:AppManifestVersion) ON (m.id)',
+    'CREATE INDEX app_manifest_version_version_idx IF NOT EXISTS FOR (m:AppManifestVersion) ON (m.version)',
+    'CREATE INDEX app_manifest_version_hash_idx IF NOT EXISTS FOR (m:AppManifestVersion) ON (m.manifestHash)',
+    'CREATE INDEX app_manifest_version_status_idx IF NOT EXISTS FOR (m:AppManifestVersion) ON (m.status)',
     'CREATE INDEX skill_framework_id_idx IF NOT EXISTS FOR (f:SkillFramework) ON (f.id)',
     'CREATE TEXT INDEX skill_framework_name_text_idx IF NOT EXISTS FOR (f:SkillFramework) ON (f.name)',
     'CREATE INDEX skill_id_idx IF NOT EXISTS FOR (s:Skill) ON (s.id)',
@@ -253,7 +276,9 @@ export * from './SkillFramework';
 export * from './Skill';
 export * from './Tag';
 export * from './Integration';
+export * from './AppManifestVersion';
 export * from './AppStoreListing';
 export * from './CredentialActivity';
 export * from './CredentialRefresh';
+export * from './ShareLink';
 export * from './StatusList';

package/src/models/share-link-constraints.ts

@@ -0,0 +1,98 @@
+import { neogma } from '@instance';
+
+/**
+ * Uniqueness rules required for the LC-2187 share lifecycle.
+ *
+ * A uniqueness constraint alone does not serialize two transactions consuming one
+ * reservation; the repository additionally holds a `:ShareLink` write lock before
+ * reading status/version/reservation state. These rules are the hard backstop that
+ * makes the resulting race fail closed instead of forking state.
+ */
+const SHARE_LINK_CONSTRAINT_QUERIES = [
+    'CREATE CONSTRAINT share_link_attachment_stage_key_unique IF NOT EXISTS FOR (a:ShareLinkAttachmentStage) REQUIRE (a.key) IS UNIQUE',
+    'CREATE CONSTRAINT share_link_attachment_id_unique IF NOT EXISTS FOR (a:ShareLinkAttachmentStage) REQUIRE (a.attachmentId) IS UNIQUE',
+    'CREATE CONSTRAINT share_attachment_owner_quota_key_unique IF NOT EXISTS FOR (q:ShareAttachmentOwnerQuota) REQUIRE (q.key) IS UNIQUE',
+    // A share id is globally unique across namespaces.
+    'CREATE CONSTRAINT share_link_id_unique IF NOT EXISTS FOR (s:ShareLink) REQUIRE (s.id) IS UNIQUE',
+    // One idempotency record per (namespace, owner, operation kind, client request).
+    'CREATE CONSTRAINT share_link_operation_key_unique IF NOT EXISTS FOR (o:ShareLinkOperation) REQUIRE (o.namespace, o.ownerProfileId, o.opKind, o.clientRequestId) IS UNIQUE',
+    // At most one in-flight reservation per share.
+    'CREATE CONSTRAINT share_link_reservation_share_unique IF NOT EXISTS FOR (r:ShareLinkReservation) REQUIRE (r.shareId) IS UNIQUE',
+    // Cleanup is bound to exactly one immutable object reference.
+    'CREATE CONSTRAINT share_content_cleanup_object_unique IF NOT EXISTS FOR (c:ShareContentCleanupJob) REQUIRE (c.objectRef) IS UNIQUE',
+    // One persisted receipt node per opaque token hash (the token itself is never stored).
+    'CREATE CONSTRAINT share_view_receipt_hash_unique IF NOT EXISTS FOR (v:ShareViewReceipt) REQUIRE (v.receiptHash) IS UNIQUE',
+];
+
+/**
+ * Non-unique indexes that keep the lifecycle queries bounded. Index creation is
+ * idempotent and shares the same readiness gate as the constraints.
+ */
+const SHARE_LINK_INDEX_QUERIES = [
+    'CREATE INDEX share_attachment_stage_owner_idx IF NOT EXISTS FOR (a:ShareLinkAttachmentStage) ON (a.namespace, a.ownerProfileId, a.status)',
+    'CREATE INDEX share_attachment_stage_expiry_idx IF NOT EXISTS FOR (a:ShareLinkAttachmentStage) ON (a.namespace, a.status, a.expiresAt)',
+    'CREATE INDEX share_link_ns_owner_idx IF NOT EXISTS FOR (s:ShareLink) ON (s.namespace, s.ownerProfileId)',
+    // Bounded owner-list keyset pagination: filters on the leading
+    // (namespace, ownerProfileId) prefix and orders by the immutable
+    // (createdAt, id) key without a full scan/sort.
+    'CREATE INDEX share_link_ns_owner_created_idx IF NOT EXISTS FOR (s:ShareLink) ON (s.namespace, s.ownerProfileId, s.createdAt, s.id)',
+    'CREATE INDEX share_link_status_idx IF NOT EXISTS FOR (s:ShareLink) ON (s.status)',
+    'CREATE INDEX share_link_operation_operation_id_idx IF NOT EXISTS FOR (o:ShareLinkOperation) ON (o.operationId)',
+    'CREATE INDEX share_link_operation_share_id_idx IF NOT EXISTS FOR (o:ShareLinkOperation) ON (o.shareId)',
+    'CREATE INDEX share_link_reservation_lease_idx IF NOT EXISTS FOR (r:ShareLinkReservation) ON (r.leaseExpiresAt)',
+    // Bounded recovery discovery enumerates expired reservations for one namespace.
+    'CREATE INDEX share_link_reservation_ns_lease_idx IF NOT EXISTS FOR (r:ShareLinkReservation) ON (r.namespace, r.leaseExpiresAt)',
+    'CREATE INDEX share_content_cleanup_due_idx IF NOT EXISTS FOR (c:ShareContentCleanupJob) ON (c.status, c.nextAttemptAt)',
+    // One-shot receipt pruning is bounded by expiry/consumed state.
+    'CREATE INDEX share_view_receipt_expiry_idx IF NOT EXISTS FOR (v:ShareViewReceipt) ON (v.expiresAt)',
+    'CREATE INDEX share_view_receipt_share_idx IF NOT EXISTS FOR (v:ShareViewReceipt) ON (v.namespace, v.shareId)',
+];
+
+type Neo4jSchemaError = {
+    code?: string;
+};
+
+const isEquivalentSchemaRuleRace = (error: unknown): boolean =>
+    (error as Neo4jSchemaError | undefined)?.code ===
+    'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists';
+
+const createShareLinkSchema = async (): Promise<void> => {
+    for (const query of [...SHARE_LINK_CONSTRAINT_QUERIES, ...SHARE_LINK_INDEX_QUERIES]) {
+        try {
+            await neogma.queryRunner.run(query);
+        } catch (error) {
+            // Concurrent service starts can both observe a missing rule before one
+            // wins creation. The losing CREATE is equivalent to the desired ready state.
+            if (!isEquivalentSchemaRuleRace(error)) throw error;
+        }
+    }
+};
+
+let constraintReadiness: Promise<void> | undefined;
+
+/**
+ * Ensures the uniqueness rules and indexes required for the share lifecycle.
+ *
+ * Every public repository method awaits this before its transaction, so a caller
+ * can never observe the "constraints not initialized" window. Concurrent callers
+ * share one attempt; a failed attempt is cleared so a later request can retry
+ * instead of leaving the repository permanently unavailable.
+ */
+export const ensureShareLinkConstraints = (): Promise<void> => {
+    if (!constraintReadiness) {
+        const pendingReadiness = createShareLinkSchema();
+        constraintReadiness = pendingReadiness;
+
+        void pendingReadiness.catch(() => {
+            if (constraintReadiness === pendingReadiness) constraintReadiness = undefined;
+        });
+    }
+
+    return constraintReadiness;
+};
+
+/** Exposed for focused tests that assert the exact schema statements. */
+export const SHARE_LINK_SCHEMA_QUERIES = [
+    ...SHARE_LINK_CONSTRAINT_QUERIES,
+    ...SHARE_LINK_INDEX_QUERIES,
+] as const;

package/src/openapi.ts

@@ -1,5 +1,6 @@
 import { generateOpenApiDocument } from 'trpc-to-openapi';
-import express, { type Express } from 'express';
+import express from 'express';
+import type { Express } from 'express';
 
 import { appRouter } from './app';
 
@@ -43,20 +44,55 @@ if (publishRequestBody && !('$ref' in publishRequestBody)) {
     const publishSchema = publishRequestBody.content?.['application/json']?.schema;
 
     if (publishSchema && !('$ref' in publishSchema)) {
+        const properties = publishSchema.properties;
+        const signedCredential = properties?.signedCredential;
+        const credential = properties?.credential;
+        const signingAuthority = properties?.signingAuthority;
+
+        if (!properties?.refreshId || !signedCredential || !credential || !signingAuthority) {
+            throw new Error('Managed refresh publication schema is missing required properties');
+        }
+
+        const commonProperties = {
+            refreshId: properties.refreshId,
+            notifyHolder: properties.notifyHolder!,
+            updateSummary: properties.updateSummary!,
+            idempotencyKey: properties.idempotencyKey!,
+        };
+        // Generator 7.25.0 loses the OpenAPI 3.1 closed-object flag. Keep the
+        // template workaround scoped to these mutually exclusive request branches.
+        const closedPublicationBranch = {
+            additionalProperties: false,
+            'x-python-forbid-extra': true,
+        } as const;
+
+        // Each branch must own its complete shape. Generators do not inherit the
+        // parent's properties into oneOf branches; enum also works in the pinned generator.
         publishSchema.oneOf = [
             {
-                properties: { mode: { const: 'issuer-signed' } },
-                required: ['signedCredential'],
-                not: {
-                    anyOf: [{ required: ['credential'] }, { required: ['signingAuthority'] }],
+                type: 'object',
+                properties: {
+                    ...commonProperties,
+                    mode: { type: 'string', enum: ['issuer-signed'] },
+                    signedCredential,
                 },
+                required: ['refreshId', 'mode', 'signedCredential'],
+                ...closedPublicationBranch,
             },
             {
-                properties: { mode: { const: 'signing-authority' } },
-                required: ['credential', 'signingAuthority'],
-                not: { required: ['signedCredential'] },
+                type: 'object',
+                properties: {
+                    ...commonProperties,
+                    mode: { type: 'string', enum: ['signing-authority'] },
+                    credential,
+                    signingAuthority,
+                },
+                required: ['refreshId', 'mode', 'credential', 'signingAuthority'],
+                ...closedPublicationBranch,
             },
         ];
+        delete publishSchema.properties;
+        delete publishSchema.required;
     }
 }
 

package/src/public-share-link-http.ts

@@ -0,0 +1,49 @@
+import type { FastifyInstance } from 'fastify';
+
+/**
+ * LC-2187 public share-link HTTP adapter seam.
+ *
+ * The Fastify OpenAPI adapter has no `responseMeta` hook, so the no-store
+ * contract for the anonymous public share-link routes is applied at the adapter
+ * boundary itself. This module is deliberately free of the server bootstrap
+ * (which listens on import) so a real Fastify instance can be exercised in
+ * tests without starting the application.
+ */
+
+/**
+ * Prefixes that identify a mounted public share-link OpenAPI request.
+ *
+ * The trpc-to-openapi Fastify adapter rewrites `request.raw.url` by stripping
+ * its `/api` base path before the handler runs, so the `onSend` hook sees
+ * `/public/share-links/...` even though the client requested
+ * `/api/public/share-links/...`. Both forms are matched (with a path-boundary
+ * check) so a sibling route such as `/public/share-links-other` is not treated
+ * as public.
+ */
+const PUBLIC_SHARE_LINK_PREFIXES = ['/api/public/share-links', '/public/share-links'] as const;
+
+/** True for the mounted public share-link OpenAPI route prefix only. */
+export const isPublicShareLinkOpenApiRequestUrl = (url: string | undefined): boolean => {
+    if (!url) return false;
+
+    const path = url.split('?')[0] ?? '';
+
+    return PUBLIC_SHARE_LINK_PREFIXES.some(
+        prefix => path === prefix || path.startsWith(`${prefix}/`)
+    );
+};
+
+/**
+ * Installs the adapter-boundary `Cache-Control: private, no-store` on every
+ * public share-link OpenAPI response, independent of any upstream cache layer.
+ * It is safe to register on any Fastify instance (tRPC-only test apps included).
+ */
+export const registerPublicShareLinkNoStore = (app: FastifyInstance): void => {
+    app.addHook('onSend', async (request, reply, payload) => {
+        if (isPublicShareLinkOpenApiRequestUrl(request.raw.url)) {
+            reply.header('Cache-Control', 'private, no-store');
+        }
+
+        return payload;
+    });
+};