@learncard/network-brain-service 3.19.1 → 4.0.1

package/src/accesslayer/share-link/attachment.ts

@@ -0,0 +1,360 @@
+import { createHash } from 'node:crypto';
+import { int } from 'neo4j-driver';
+import type { ShareLinkAttachment } from '@learncard/types';
+import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
+import { failShareLink } from './errors';
+import {
+    enqueueCleanupJob,
+    lockShare,
+    readNodeProperties,
+    readReservation,
+    toShareLinkRecord,
+    toShareLinkReservationRecord,
+    normalizeNeo4jValue,
+} from './helpers';
+import {
+    withShareLinkTransaction,
+    type ShareLinkTransaction,
+    type ShareLinkTransactionOptions,
+} from './transaction';
+
+export type ShareAttachmentBinding = {
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    attachmentId: string;
+    chunkCount: number;
+};
+
+export const shareAttachmentObjectId = (attachmentId: string, chunkIndex: number): string =>
+    `resume-pdf-${attachmentId}-${chunkIndex}`;
+export const shareAttachmentTuple = (binding: ShareAttachmentBinding, chunkIndex: number) => ({
+    namespace: binding.namespace,
+    ownerProfileId: binding.ownerProfileId,
+    shareId: binding.shareId,
+    contentVersion: binding.contentVersion,
+    objectId: shareAttachmentObjectId(binding.attachmentId, chunkIndex),
+    operationId: binding.attachmentId,
+});
+
+const stageKey = (binding: ShareAttachmentBinding): string =>
+    createHash('sha256')
+        .update(
+            JSON.stringify([
+                binding.namespace,
+                binding.ownerProfileId,
+                binding.shareId,
+                binding.contentVersion,
+                binding.attachmentId,
+            ])
+        )
+        .digest('hex');
+
+const lockStage = async (tx: ShareLinkTransaction, binding: ShareAttachmentBinding) => {
+    const result = await tx.run(
+        `MATCH (a:ShareLinkAttachmentStage {key: $key})
+        SET a.lockTick = coalesce(a.lockTick, 0) + 1 RETURN a`,
+        { key: stageKey(binding) }
+    );
+    const props = readNodeProperties(result, 'a');
+    if (props && props.chunkCount !== binding.chunkCount) {
+        failShareLink('CONFLICT', 'attachment staging conflict');
+    }
+    return props;
+};
+
+/** Stage guard is durable; remote I/O happens only after this transaction closes. */
+export const beginShareAttachmentChunk = async (
+    binding: ShareAttachmentBinding,
+    chunkIndex: number
+): Promise<void> => {
+    if (
+        !Number.isInteger(binding.chunkCount) ||
+        binding.chunkCount < 1 ||
+        binding.chunkCount > 16 ||
+        !Number.isInteger(chunkIndex) ||
+        chunkIndex < 0 ||
+        chunkIndex >= binding.chunkCount
+    )
+        failShareLink('INVALID_INPUT', 'invalid attachment chunk');
+    await ensureShareLinkConstraints();
+    await withShareLinkTransaction(async tx => {
+        const shareProps = await lockShare(tx, binding.shareId);
+        if (shareProps) {
+            const share = toShareLinkRecord(shareProps);
+            if (
+                share.namespace !== binding.namespace ||
+                share.ownerProfileId !== binding.ownerProfileId
+            ) {
+                failShareLink('NOT_FOUND', 'share not found');
+            }
+            if (
+                share.status === 'stopped' ||
+                !(
+                    (share.status === 'pending' && binding.contentVersion === 1) ||
+                    binding.contentVersion === share.contentVersion + 1 ||
+                    (binding.contentVersion === share.contentVersion &&
+                        share.attachmentId === binding.attachmentId &&
+                        share.attachmentChunkCount === binding.chunkCount)
+                )
+            )
+                failShareLink('CONFLICT', 'attachment version conflict');
+            const pending = await readReservation(tx, binding.shareId);
+            if (pending) {
+                const reservation = toShareLinkReservationRecord(pending);
+                if (
+                    reservation.contentVersion !== binding.contentVersion ||
+                    reservation.attachmentId !== binding.attachmentId ||
+                    reservation.attachmentChunkCount !== binding.chunkCount
+                ) {
+                    failShareLink('CONFLICT', 'another publication is pending');
+                }
+            }
+        } else if (binding.contentVersion !== 1) {
+            failShareLink('NOT_FOUND', 'share not found');
+        }
+        // Serialize pre-create stages by owner as well as by share, so simultaneous
+        // random IDs cannot exceed the bounded uncommitted storage allowance.
+        const quotaKey = createHash('sha256')
+            .update(JSON.stringify([binding.namespace, binding.ownerProfileId]))
+            .digest('hex');
+        await tx.run(
+            `MERGE (q:ShareAttachmentOwnerQuota {key: $quotaKey})
+            ON CREATE SET q.namespace = $namespace, q.ownerProfileId = $ownerProfileId
+            SET q.lockTick = coalesce(q.lockTick, 0) + 1`,
+            {
+                quotaKey,
+                namespace: binding.namespace,
+                ownerProfileId: binding.ownerProfileId,
+            }
+        );
+        const existing = await lockStage(tx, binding);
+        if (!existing) {
+            const result = await tx.run(
+                `MATCH (a:ShareLinkAttachmentStage)
+                WHERE a.namespace = $namespace AND a.ownerProfileId = $ownerProfileId
+                    AND a.status = 'staging' AND a.expiresAt > $now
+                RETURN count(a) AS count`,
+                {
+                    namespace: binding.namespace,
+                    ownerProfileId: binding.ownerProfileId,
+                    now: new Date().toISOString(),
+                }
+            );
+            const count = normalizeNeo4jValue(result.records[0]?.get('count'));
+            if (typeof count !== 'number' || count >= 8)
+                failShareLink('PRECONDITION_FAILED', 'attachment staging limit reached');
+        }
+        await tx.run(
+            `MERGE (a:ShareLinkAttachmentStage {key: $key})
+            ON CREATE SET a += $props
+            SET a.lockTick = coalesce(a.lockTick, 0) + 1 RETURN a`,
+            {
+                key: stageKey(binding),
+                props: {
+                    ...binding,
+                    status: 'staging',
+                    completedChunks: [],
+                    createdAt: new Date().toISOString(),
+                    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+                },
+            }
+        );
+        const stage = await lockStage(tx, binding);
+        if (!stage || stage.status === 'deleted')
+            failShareLink('CONFLICT', 'attachment staging conflict');
+        if (
+            stage.status === 'staging' &&
+            typeof stage.expiresAt === 'string' &&
+            stage.expiresAt <= new Date().toISOString()
+        ) {
+            failShareLink('CONFLICT', 'attachment staging expired');
+        }
+    });
+};
+
+/**
+ * Record successful immutable puts even if staging expired during remote I/O.
+ * This is bookkeeping, not publication authority: pin/finalize enforce expiry,
+ * and maintenance cleans up an expired, uncommitted stage.
+ */
+export const completeShareAttachmentChunk = async (
+    binding: ShareAttachmentBinding,
+    chunkIndex: number
+): Promise<void> => {
+    await withShareLinkTransaction(async tx => {
+        const stage = await lockStage(tx, binding);
+        if (!stage || stage.status === 'deleted')
+            failShareLink('CONFLICT', 'attachment staging conflict');
+        await tx.run(
+            `MATCH (a:ShareLinkAttachmentStage {key: $key})
+            SET a.completedChunks = CASE WHEN $chunkIndex IN a.completedChunks THEN a.completedChunks
+                ELSE a.completedChunks + $chunkIndex END`,
+            { key: stageKey(binding), chunkIndex }
+        );
+    });
+};
+
+/** Called while the share lock is held; pins complete staged chunks to request intent. */
+export const pinShareAttachment = async (
+    tx: ShareLinkTransaction,
+    binding: ShareAttachmentBinding,
+    requestHash: string
+): Promise<void> => {
+    const stage = await lockStage(tx, binding);
+    if (
+        !stage ||
+        stage.status === 'deleted' ||
+        (stage.requestHash !== undefined &&
+            stage.requestHash !== null &&
+            stage.requestHash !== requestHash)
+    ) {
+        failShareLink('PRECONDITION_FAILED', 'attachment is not ready');
+    }
+    if (
+        stage.status === 'staging' &&
+        typeof stage.expiresAt === 'string' &&
+        stage.expiresAt <= new Date().toISOString()
+    ) {
+        failShareLink('PRECONDITION_FAILED', 'attachment staging expired');
+    }
+    const completed = stage.completedChunks;
+    if (
+        !Array.isArray(completed) ||
+        !Array.from({ length: binding.chunkCount }, (_, index) => index).every(index =>
+            completed.includes(index)
+        )
+    )
+        failShareLink('PRECONDITION_FAILED', 'attachment is incomplete');
+    await tx.run(
+        `MATCH (a:ShareLinkAttachmentStage {key: $key}) SET a.status = 'pinned',
+        a.requestHash = $requestHash`,
+        { key: stageKey(binding), requestHash }
+    );
+};
+
+export const verifyPinnedShareAttachment = async (
+    tx: ShareLinkTransaction,
+    binding: ShareAttachmentBinding,
+    requestHash: string
+): Promise<void> => {
+    const stage = await lockStage(tx, binding);
+    if (!stage || stage.status !== 'pinned' || stage.requestHash !== requestHash) {
+        failShareLink('PRECONDITION_FAILED', 'attachment is not ready');
+    }
+};
+
+/** Queues only exact tuples, after withdrawing graph authority to commit those bytes. */
+export const queueShareAttachmentCleanup = async (
+    tx: ShareLinkTransaction,
+    binding: ShareAttachmentBinding,
+    reason: 'superseded' | 'abandoned' | 'stopped',
+    now: string
+): Promise<void> => {
+    const stage = await lockStage(tx, binding);
+    if (stage)
+        await tx.run(`MATCH (a:ShareLinkAttachmentStage {key: $key}) SET a.status = 'deleted'`, {
+            key: stageKey(binding),
+        });
+    for (let chunkIndex = 0; chunkIndex < binding.chunkCount; chunkIndex++) {
+        const tuple = shareAttachmentTuple(binding, chunkIndex);
+        await enqueueCleanupJob(tx, { ...tuple, objectRef: tuple.objectId, reason, now });
+    }
+};
+
+/** Refuses active or in-flight assets; a tombstoned stage can never be repinned. */
+export const deleteUnreferencedShareAttachment = async (
+    binding: ShareAttachmentBinding
+): Promise<boolean> => {
+    await ensureShareLinkConstraints();
+    return withShareLinkTransaction(async tx => {
+        const shareProps = await lockShare(tx, binding.shareId);
+        if (shareProps) {
+            const share = toShareLinkRecord(shareProps);
+            if (
+                share.namespace !== binding.namespace ||
+                share.ownerProfileId !== binding.ownerProfileId
+            ) {
+                failShareLink('NOT_FOUND', 'share not found');
+            }
+            if (
+                share.attachmentId === binding.attachmentId &&
+                share.contentVersion === binding.contentVersion
+            )
+                return false;
+            const props = await readReservation(tx, binding.shareId);
+            const reservation = props ? toShareLinkReservationRecord(props) : null;
+            if (
+                reservation?.attachmentId === binding.attachmentId &&
+                reservation.contentVersion === binding.contentVersion
+            )
+                return false;
+        }
+        const stage = await lockStage(tx, binding);
+        if (!stage) return false;
+        if (stage.status === 'pinned') return false;
+        await queueShareAttachmentCleanup(tx, binding, 'abandoned', new Date().toISOString());
+        return true;
+    });
+};
+
+export const attachmentBindingFor = (
+    scope: { namespace: string; ownerProfileId: string; shareId: string },
+    contentVersion: number,
+    attachment: ShareLinkAttachment
+): ShareAttachmentBinding => ({
+    ...scope,
+    contentVersion,
+    attachmentId: attachment.id,
+    chunkCount: attachment.chunkCount,
+});
+
+/** Bounded periodic collection of never-committed stages after their 24-hour retry window. */
+export const expireShareAttachmentStages = async (input: {
+    namespace: string;
+    limit?: number;
+    now?: Date;
+    transaction?: ShareLinkTransactionOptions;
+}): Promise<number> => {
+    if (!input.namespace) failShareLink('INVALID_INPUT', 'namespace is required');
+    const limit = Math.max(1, Math.min(10, input.limit ?? 10));
+    return withShareLinkTransaction(async tx => {
+        const candidates = await tx.run(
+            `MATCH (a:ShareLinkAttachmentStage)
+            WHERE a.namespace = $namespace AND a.status = 'staging' AND a.expiresAt <= $now
+            RETURN a ORDER BY a.expiresAt LIMIT $limit`,
+            {
+                namespace: input.namespace,
+                now: (input.now ?? new Date()).toISOString(),
+                limit: int(limit),
+            }
+        );
+        let queued = 0;
+        for (let index = 0; index < candidates.records.length; index++) {
+            const props = readNodeProperties(candidates, 'a', index);
+            if (!props) continue;
+            const binding: ShareAttachmentBinding = {
+                namespace: String(props.namespace),
+                ownerProfileId: String(props.ownerProfileId),
+                shareId: String(props.shareId),
+                attachmentId: String(props.attachmentId),
+                contentVersion: Number(props.contentVersion),
+                chunkCount: Number(props.chunkCount),
+            };
+            await lockShare(tx, binding.shareId);
+            const stage = await lockStage(tx, binding);
+            const now = (input.now ?? new Date()).toISOString();
+            if (
+                !stage ||
+                stage.status !== 'staging' ||
+                typeof stage.expiresAt !== 'string' ||
+                stage.expiresAt > now
+            )
+                continue;
+            await queueShareAttachmentCleanup(tx, binding, 'abandoned', now);
+            queued++;
+        }
+        return queued;
+    }, input.transaction);
+};

package/src/accesslayer/share-link/finalize.ts

@@ -5,6 +5,7 @@ import type { ShareLinkPolicySnapshot } from '@helpers/share-link-policy/types';
 
 import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
 import { failShareLink } from './errors';
+import { verifyPinnedShareAttachment, queueShareAttachmentCleanup } from './attachment';
 import {
     deleteReservation,
     enqueueCleanupJob,
@@ -157,12 +158,33 @@ export const finalizeReservation = async (
             }
 
             const previousObjectRef = share.activeObjectRef;
+            if (
+                reservation.contentVersion !== null &&
+                reservation.attachmentId &&
+                reservation.attachmentChunkCount
+            ) {
+                if (input.verifiedAttachmentId !== reservation.attachmentId) {
+                    failShareLink('PRECONDITION_FAILED', 'attachment was not verified');
+                }
+                await verifyPinnedShareAttachment(
+                    tx,
+                    {
+                        namespace: reservation.namespace,
+                        ownerProfileId: reservation.ownerProfileId,
+                        shareId: reservation.shareId,
+                        contentVersion: reservation.contentVersion,
+                        attachmentId: reservation.attachmentId,
+                        chunkCount: reservation.attachmentChunkCount,
+                    },
+                    reservation.requestHash
+                );
+            }
             const nextObjectRef = reservation.objectRef ?? share.activeObjectRef;
             const nextContentVersion = reservation.contentVersion ?? share.contentVersion;
 
-            // A fresh graph-local recheck is needed before enabling counting.
-            // In particular, shares created while age was unavailable retain
-            // an unknown snapshot until the owner explicitly updates them.
+            // Unknown snapshots and old service restrictions may be refreshed on
+            // explicit edits, but only after a fresh graph-local check. The
+            // reservation still caps eligibility for stale replays and recovery.
             const currentPolicy: ShareLinkPolicySnapshot = {
                 isMinor: share.minorPolicyIsMinor,
                 policyResolved: share.minorPolicyResolved,
@@ -172,18 +194,23 @@ export const finalizeReservation = async (
             const checkedPolicy = input.resolveCurrentPolicy
                 ? await input
                       .resolveCurrentPolicy(tx, share.ownerProfileId, now)
-                      .catch(() => DEFAULT_SHARE_LINK_POLICY)
+                      .catch(() => ({ ...DEFAULT_SHARE_LINK_POLICY, isServiceProfile: false }))
                 : null;
             const reservationPolicy = checkedPolicy
                 ? mergeShareLinkPolicyConservatively(reservation.policy, checkedPolicy)
                 : mergeShareLinkPolicyConservatively(reservation.policy, currentPolicy);
+            const mayRefreshExplicitService =
+                checkedPolicy?.isServiceProfile === true &&
+                checkedPolicy.isMinor === false &&
+                reservation.opKind === 'update';
             const mayReplaceUnknown =
                 checkedPolicy !== null &&
                 !currentPolicy.policyResolved &&
                 (reservation.opKind === 'create' || reservation.opKind === 'update');
-            const effectivePolicy = mayReplaceUnknown
-                ? reservationPolicy
-                : mergeShareLinkPolicyConservatively(currentPolicy, reservationPolicy);
+            const effectivePolicy =
+                mayRefreshExplicitService || mayReplaceUnknown
+                    ? reservationPolicy
+                    : mergeShareLinkPolicyConservatively(currentPolicy, reservationPolicy);
 
             await tx.run(
                 `MATCH (s:ShareLink {id: $shareId})
@@ -193,6 +220,12 @@ export const finalizeReservation = async (
                     props: {
                         version: share.version + 1,
                         contentVersion: nextContentVersion,
+                        attachmentId: reservation.objectRef
+                            ? (reservation.attachmentId ?? null)
+                            : (share.attachmentId ?? null),
+                        attachmentChunkCount: reservation.objectRef
+                            ? (reservation.attachmentChunkCount ?? null)
+                            : (share.attachmentChunkCount ?? null),
                         status: 'active',
                         contentState: 'finalized',
                         activeObjectRef: nextObjectRef,
@@ -244,6 +277,21 @@ export const finalizeReservation = async (
             let cleanupQueuedFor: string | null = null;
 
             if (previousObjectRef && previousObjectRef !== nextObjectRef) {
+                if (share.attachmentId && share.attachmentChunkCount) {
+                    await queueShareAttachmentCleanup(
+                        tx,
+                        {
+                            namespace: share.namespace,
+                            ownerProfileId: share.ownerProfileId,
+                            shareId: share.id,
+                            contentVersion: share.contentVersion,
+                            attachmentId: share.attachmentId,
+                            chunkCount: share.attachmentChunkCount,
+                        },
+                        'superseded',
+                        nowIso
+                    );
+                }
                 await enqueueCleanupJob(tx, {
                     objectRef: previousObjectRef,
                     operationId: share.activeObjectOperationId!,

package/src/accesslayer/share-link/helpers.ts

@@ -1,6 +1,7 @@
 import { randomBytes, randomUUID } from 'node:crypto';
 
 import type { ShareLinkOperationKind } from '@helpers/share-link-lifecycle';
+import type { ShareLinkPolicySnapshot } from '@helpers/share-link-policy/types';
 
 import type { ShareContentState, ShareLinkRecord, ShareLinkStatus } from '../../models/ShareLink';
 import type { Neo4jQueryResult, ShareLinkTransaction } from './transaction';
@@ -94,6 +95,8 @@ export const toShareLinkRecord = (props: Record<string, unknown>): ShareLinkReco
     ownerProfileId: asString(props.ownerProfileId),
     version: asNumber(props.version, 1),
     contentVersion: asNumber(props.contentVersion, 1),
+    attachmentId: asNullableString(props.attachmentId),
+    attachmentChunkCount: asNullableNumber(props.attachmentChunkCount),
     generation: asNumber(props.generation, 1),
     status: isOneOf(props.status, SHARE_LINK_STATUSES) ? props.status : 'pending',
     contentState: isOneOf(props.contentState, SHARE_CONTENT_STATES)
@@ -135,6 +138,8 @@ export const toShareLinkReservationRecord = (
     operationId: asString(props.operationId),
     objectRef: asNullableString(props.objectRef),
     contentVersion: asNullableNumber(props.contentVersion),
+    attachmentId: asNullableString(props.attachmentId),
+    attachmentChunkCount: asNullableNumber(props.attachmentChunkCount),
     baseVersion: asNumber(props.baseVersion, 1),
     baseContentVersion: asNumber(props.baseContentVersion, 1),
     contentHash: asNullableString(props.contentHash),
@@ -160,6 +165,20 @@ export const toShareLinkReservationRecord = (
     updatedAt: asString(props.updatedAt),
 });
 
+/** Legacy operation records have no policy ceiling; callers fall back to their reservation. */
+export const toShareLinkOperationPolicy = (
+    props: Record<string, unknown>
+): ShareLinkPolicySnapshot | null => {
+    if (typeof props.policyViewCountingEnabled !== 'boolean') return null;
+
+    return {
+        isMinor: asNullableBoolean(props.policyIsMinor),
+        policyResolved: asBoolean(props.policyResolved, false),
+        defaultExpiryDays: asNumber(props.policyDefaultExpiryDays, 30) === 365 ? 365 : 30,
+        viewCountingEnabled: props.policyViewCountingEnabled,
+    };
+};
+
 export const toShareLinkOperationRecord = (
     props: Record<string, unknown>
 ): ShareLinkOperationRecord => ({
@@ -296,6 +315,7 @@ export type WriteOperationInput = ShareLinkOperationKey & {
     requestHash: string;
     now: string;
     pruneAfter: string;
+    policy?: ShareLinkPolicySnapshot;
 };
 
 /**
@@ -322,8 +342,19 @@ export const writeOperationInProgress = async (
              o.status = 'in_progress',
              o.resultJson = null,
              o.resultVersion = null,
-             o.updatedAt = $now`,
-        input
+             o.updatedAt = $now
+         SET o += $policyProps`,
+        {
+            ...input,
+            policyProps: input.policy
+                ? {
+                      policyIsMinor: input.policy.isMinor,
+                      policyResolved: input.policy.policyResolved,
+                      policyDefaultExpiryDays: input.policy.defaultExpiryDays,
+                      policyViewCountingEnabled: input.policy.viewCountingEnabled,
+                  }
+                : {},
+        }
     );
 };
 

package/src/accesslayer/share-link/recovery.ts

@@ -11,6 +11,7 @@ import { neogma } from '@instance';
 
 import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
 import { failShareLink } from './errors';
+import { queueShareAttachmentCleanup } from './attachment';
 import {
     deleteReservation,
     enqueueCleanupJob,
@@ -514,6 +515,25 @@ export const abandonRecoveredReservation = async (
             }
 
             let cleanupQueuedFor: string | null = null;
+            if (
+                reservation.attachmentId &&
+                reservation.attachmentChunkCount &&
+                reservation.contentVersion
+            ) {
+                await queueShareAttachmentCleanup(
+                    tx,
+                    {
+                        namespace: reservation.namespace,
+                        ownerProfileId: reservation.ownerProfileId,
+                        shareId: reservation.shareId,
+                        contentVersion: reservation.contentVersion,
+                        attachmentId: reservation.attachmentId,
+                        chunkCount: reservation.attachmentChunkCount,
+                    },
+                    'abandoned',
+                    nowIso
+                );
+            }
 
             if (reservation.objectRef) {
                 await enqueueCleanupJob(tx, {