deepline 0.1.182 → 0.1.184

package/dist/bundling-sources/shared_libs/play-runtime/work-receipt-state-machine.ts

@@ -0,0 +1,437 @@
+export type WorkReceiptStateStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'skipped';
+
+export type WorkReceiptStateInput = {
+  status: WorkReceiptStateStatus;
+  runId?: string | null;
+  failureKind?: 'terminal' | 'repairable' | null;
+  leaseId?: string | null;
+  leaseOwnerRunId?: string | null;
+  leaseOwnerAttempt?: number | null;
+  leaseExpiresAt?: string | null;
+};
+
+export type WorkReceiptLeaseState =
+  | { kind: 'none' }
+  | {
+      kind: 'active';
+      leaseId: string;
+      ownerRunId: string;
+      ownerAttempt: number;
+      expiresAt: string;
+      expiresAtMs: number;
+    }
+  | {
+      kind: 'expired';
+      leaseId: string | null;
+      ownerRunId: string;
+      ownerAttempt: number;
+      expiresAt: string;
+      expiresAtMs: number;
+    }
+  | {
+      kind: 'invalid';
+      reason:
+        | 'missing_owner'
+        | 'missing_expiry'
+        | 'missing_lease_id'
+        | 'invalid_expiry';
+      leaseId: string | null;
+      ownerRunId: string | null;
+      expiresAt: string | null;
+    };
+
+export type WorkReceiptInvalidLeaseReason = Extract<
+  WorkReceiptLeaseState,
+  { kind: 'invalid' }
+>['reason'];
+
+export type WorkReceiptState =
+  | {
+      kind: 'pending';
+      terminal: false;
+      reusable: false;
+      lease: WorkReceiptLeaseState;
+    }
+  | {
+      kind: 'running';
+      terminal: false;
+      reusable: false;
+      lease: WorkReceiptLeaseState;
+    }
+  | {
+      kind: 'completed';
+      terminal: true;
+      reusable: true;
+      lease: WorkReceiptLeaseState;
+    }
+  | {
+      kind: 'skipped';
+      terminal: true;
+      reusable: true;
+      lease: WorkReceiptLeaseState;
+    }
+  | {
+      kind: 'failed';
+      terminal: true;
+      reusable: false;
+      lease: WorkReceiptLeaseState;
+    };
+
+export type WorkReceiptClaimDecision =
+  | { kind: 'claim' }
+  | { kind: 'reuse_terminal' }
+  | {
+      kind: 'blocked_active_lease';
+      status: WorkReceiptStateStatus;
+      ownerRunId: string | null;
+      leaseId: string | null;
+    }
+  | {
+      kind: 'blocked_running';
+      ownerRunId: string | null;
+      leaseId: string | null;
+    }
+  | {
+      kind: 'blocked_invalid_lease';
+      reason: WorkReceiptInvalidLeaseReason;
+      status: WorkReceiptStateStatus;
+    }
+  | { kind: 'blocked_failed' };
+
+export type WorkReceiptOwnerOperationDecision =
+  | { kind: 'allow' }
+  | {
+      kind: 'reject';
+      reason:
+        | 'missing_receipt'
+        | 'not_running'
+        | 'owner_mismatch'
+        | 'attempt_mismatch'
+        | 'lease_mismatch'
+        | 'missing_request_lease';
+    };
+
+export type WorkReceiptOwnerOperationInput = {
+  receipt: WorkReceiptStateInput | null;
+  ownerRunId?: string | null;
+  ownerRunAttempt?: number | null;
+  leaseId?: string | null;
+};
+
+function normalize(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function normalizeAttempt(value: number | null | undefined): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, Math.floor(value))
+    : 0;
+}
+
+export function classifyWorkReceiptLeaseState(
+  receipt: WorkReceiptStateInput,
+  nowMs: number,
+): WorkReceiptLeaseState {
+  const ownerRunId =
+    normalize(receipt.leaseOwnerRunId) ?? normalize(receipt.runId);
+  const leaseId = normalize(receipt.leaseId);
+  const expiresAt = normalize(receipt.leaseExpiresAt);
+  if (!leaseId && !expiresAt) {
+    return { kind: 'none' };
+  }
+  if (!ownerRunId) {
+    return {
+      kind: 'invalid',
+      reason: 'missing_owner',
+      leaseId,
+      ownerRunId,
+      expiresAt,
+    };
+  }
+  if (!expiresAt) {
+    return {
+      kind: 'invalid',
+      reason: 'missing_expiry',
+      leaseId,
+      ownerRunId,
+      expiresAt,
+    };
+  }
+  const expiresAtMs = Date.parse(expiresAt);
+  if (!Number.isFinite(expiresAtMs)) {
+    return {
+      kind: 'invalid',
+      reason: 'invalid_expiry',
+      leaseId,
+      ownerRunId,
+      expiresAt,
+    };
+  }
+  if (expiresAtMs <= nowMs) {
+    return {
+      kind: 'expired',
+      leaseId,
+      ownerRunId,
+      ownerAttempt: normalizeAttempt(receipt.leaseOwnerAttempt),
+      expiresAt,
+      expiresAtMs,
+    };
+  }
+  if (!leaseId) {
+    return {
+      kind: 'invalid',
+      reason: 'missing_lease_id',
+      leaseId,
+      ownerRunId,
+      expiresAt,
+    };
+  }
+  return {
+    kind: 'active',
+    leaseId,
+    ownerRunId,
+    ownerAttempt: normalizeAttempt(receipt.leaseOwnerAttempt),
+    expiresAt,
+    expiresAtMs,
+  };
+}
+
+export function classifyWorkReceiptState(
+  receipt: WorkReceiptStateInput,
+  nowMs: number,
+): WorkReceiptState {
+  const lease = classifyWorkReceiptLeaseState(receipt, nowMs);
+  switch (receipt.status) {
+    case 'pending':
+      return { kind: 'pending', terminal: false, reusable: false, lease };
+    case 'running':
+      return { kind: 'running', terminal: false, reusable: false, lease };
+    case 'completed':
+      return { kind: 'completed', terminal: true, reusable: true, lease };
+    case 'skipped':
+      return { kind: 'skipped', terminal: true, reusable: true, lease };
+    case 'failed':
+      return { kind: 'failed', terminal: true, reusable: false, lease };
+    default:
+      return assertNever(receipt.status);
+  }
+}
+
+export function decideWorkReceiptClaim(input: {
+  receipt: WorkReceiptStateInput | null;
+  claimantRunId?: string | null;
+  claimantRunAttempt?: number | null;
+  reclaimRunning?: boolean;
+  forceRefresh?: boolean;
+  forceFailedRefresh?: boolean;
+  nowMs: number;
+}): WorkReceiptClaimDecision {
+  if (!input.receipt) return { kind: 'claim' };
+  const state = classifyWorkReceiptState(input.receipt, input.nowMs);
+  if (state.reusable && input.forceRefresh !== true) {
+    return { kind: 'reuse_terminal' };
+  }
+  if (state.kind === 'failed' && input.forceRefresh !== true) {
+    if (input.forceFailedRefresh === true) {
+      return { kind: 'claim' };
+    }
+    const claimantRunId = normalize(input.claimantRunId);
+    const ownerRunId = normalize(input.receipt.runId);
+    const claimantRunAttempt = normalizeAttempt(input.claimantRunAttempt);
+    const ownerAttempt = normalizeAttempt(input.receipt.leaseOwnerAttempt);
+    if (
+      input.receipt.failureKind === 'repairable' &&
+      claimantRunId !== null &&
+      ownerRunId !== null &&
+      (claimantRunId !== ownerRunId || ownerAttempt < claimantRunAttempt)
+    ) {
+      return { kind: 'claim' };
+    }
+    return { kind: 'blocked_failed' };
+  }
+  if (state.kind === 'pending' || state.kind === 'running') {
+    if (state.lease.kind === 'active') {
+      if (
+        (state.kind !== 'running' ||
+          input.reclaimRunning === true ||
+          input.forceRefresh === true) &&
+        state.lease.ownerRunId !== null &&
+        state.lease.ownerRunId === normalize(input.claimantRunId) &&
+        state.lease.ownerAttempt < normalizeAttempt(input.claimantRunAttempt)
+      ) {
+        return { kind: 'claim' };
+      }
+      return {
+        kind: 'blocked_active_lease',
+        status: state.kind,
+        ownerRunId: state.lease.ownerRunId,
+        leaseId: state.lease.leaseId,
+      };
+    }
+    if (state.lease.kind === 'invalid') {
+      return {
+        kind: 'blocked_invalid_lease',
+        reason: state.lease.reason,
+        status: state.kind,
+      };
+    }
+    if (input.forceRefresh === true && input.reclaimRunning === true) {
+      return { kind: 'claim' };
+    }
+    if (state.kind === 'pending') {
+      return { kind: 'claim' };
+    }
+    if (
+      input.reclaimRunning === true &&
+      (state.lease.kind === 'expired' || state.lease.kind === 'none')
+    ) {
+      return { kind: 'claim' };
+    }
+    return {
+      kind: 'blocked_running',
+      ownerRunId:
+        state.lease.kind === 'expired'
+          ? state.lease.ownerRunId
+          : normalize(input.receipt.runId),
+      leaseId:
+        state.lease.kind === 'expired'
+          ? state.lease.leaseId
+          : normalize(input.receipt.leaseId),
+    };
+  }
+  if (
+    input.forceRefresh === true &&
+    (state.kind === 'completed' || state.kind === 'skipped')
+  ) {
+    if (state.lease.kind === 'active') {
+      if (
+        state.lease.ownerRunId !== null &&
+        state.lease.ownerRunId === normalize(input.claimantRunId) &&
+        state.lease.ownerAttempt < normalizeAttempt(input.claimantRunAttempt)
+      ) {
+        return { kind: 'claim' };
+      }
+      return {
+        kind: 'blocked_active_lease',
+        status: state.kind,
+        ownerRunId: state.lease.ownerRunId,
+        leaseId: state.lease.leaseId,
+      };
+    }
+    if (state.lease.kind === 'invalid') {
+      return {
+        kind: 'blocked_invalid_lease',
+        reason: state.lease.reason,
+        status: state.kind,
+      };
+    }
+  }
+  if (input.forceRefresh === true) {
+    return { kind: 'claim' };
+  }
+  return { kind: 'claim' };
+}
+
+function ownerRunIdForReceipt(receipt: WorkReceiptStateInput): string | null {
+  return normalize(receipt.leaseOwnerRunId) ?? normalize(receipt.runId);
+}
+
+function baseRunningOwnerDecision(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  if (!input.receipt) {
+    return { kind: 'reject', reason: 'missing_receipt' };
+  }
+  if (input.receipt.status !== 'running') {
+    return { kind: 'reject', reason: 'not_running' };
+  }
+  const ownerRunId = normalize(input.ownerRunId);
+  if (!ownerRunId || ownerRunIdForReceipt(input.receipt) !== ownerRunId) {
+    return { kind: 'reject', reason: 'owner_mismatch' };
+  }
+  if (
+    normalizeAttempt(input.receipt.leaseOwnerAttempt) !==
+    normalizeAttempt(input.ownerRunAttempt)
+  ) {
+    return { kind: 'reject', reason: 'attempt_mismatch' };
+  }
+  return { kind: 'allow' };
+}
+
+/**
+ * Law for complete/fail/skip. A terminal write may only be made by the
+ * running receipt owner for the same attempt. When the receipt has a lease id,
+ * the writer must also present that exact lease id; legacy unleased running
+ * receipts remain writable by their run+attempt owner during the migration.
+ */
+export function decideWorkReceiptTerminalWrite(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  const ownerDecision = baseRunningOwnerDecision(input);
+  if (ownerDecision.kind === 'reject') return ownerDecision;
+
+  const receiptLeaseId = normalize(input.receipt?.leaseId);
+  if (!receiptLeaseId) return { kind: 'allow' };
+  if (receiptLeaseId !== normalize(input.leaseId)) {
+    return { kind: 'reject', reason: 'lease_mismatch' };
+  }
+  return { kind: 'allow' };
+}
+
+/**
+ * Law for a single suspended receipt release. It uses the same ownership fence
+ * as terminal writes: only the running owner can release, and a leased receipt
+ * requires the exact lease id.
+ */
+export function decideWorkReceiptExactRelease(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  return decideWorkReceiptTerminalWrite(input);
+}
+
+/**
+ * Law for run-fatal teardown. The owner may release all of its still-running
+ * receipts for the same attempt without threading every per-receipt lease id.
+ * It must never match another run or another attempt.
+ */
+export function decideWorkReceiptOwnerRelease(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  return baseRunningOwnerDecision(input);
+}
+
+/**
+ * Law for heartbeat. Heartbeats are stricter than terminal writes: they renew a
+ * specific live lease, so both receipt and request must carry the same lease id.
+ */
+export function decideWorkReceiptHeartbeat(
+  input: WorkReceiptOwnerOperationInput,
+): WorkReceiptOwnerOperationDecision {
+  const ownerDecision = baseRunningOwnerDecision(input);
+  if (ownerDecision.kind === 'reject') return ownerDecision;
+
+  const requestLeaseId = normalize(input.leaseId);
+  if (!requestLeaseId) {
+    return { kind: 'reject', reason: 'missing_request_lease' };
+  }
+  if (normalize(input.receipt?.leaseId) !== requestLeaseId) {
+    return { kind: 'reject', reason: 'lease_mismatch' };
+  }
+  return { kind: 'allow' };
+}
+
+export function isReusableWorkReceiptState(
+  receipt: WorkReceiptStateInput,
+): boolean {
+  return receipt.status === 'completed' || receipt.status === 'skipped';
+}
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled work receipt state: ${String(value)}`);
+}

package/dist/bundling-sources/shared_libs/play-runtime/work-receipts.ts

@@ -1,3 +1,29 @@
+import { isReusableWorkReceiptState } from './work-receipt-state-machine';
+
+export type WorkReceiptFailureKind = 'terminal' | 'repairable';
+
+export const WORK_RECEIPT_FAILURE_KIND_CODE: Record<
+  WorkReceiptFailureKind,
+  number
+> = {
+  terminal: 0,
+  repairable: 1,
+};
+
+export function workReceiptFailureKindFromCode(
+  value: unknown,
+): WorkReceiptFailureKind {
+  return Number(value) === WORK_RECEIPT_FAILURE_KIND_CODE.repairable
+    ? 'repairable'
+    : 'terminal';
+}
+
+export function workReceiptFailureKindCode(
+  value: WorkReceiptFailureKind | null | undefined,
+): number {
+  return WORK_RECEIPT_FAILURE_KIND_CODE[value ?? 'terminal'];
+}
+
 export type WorkReceiptStatus =
   | 'pending'
   | 'running'
@@ -10,7 +36,12 @@ export type WorkReceipt = {
   status: WorkReceiptStatus;
   output?: unknown;
   error?: string | null;
+  failureKind?: WorkReceiptFailureKind | null;
   runId?: string | null;
+  leaseId?: string | null;
+  leaseOwnerRunId?: string | null;
+  leaseOwnerAttempt?: number | null;
+  leaseExpiresAt?: string | null;
   updatedAt?: string | null;
 };
 
@@ -18,26 +49,57 @@ export type WorkReceiptCommand = {
   playName: string;
   runId: string;
   key: string;
+  leaseId?: string | null;
+  runAttempt?: number | null;
+  leaseTtlMs?: number | null;
+  leaseAware?: boolean;
   reclaimRunning?: boolean;
   forceRefresh?: boolean;
+  forceFailedRefresh?: boolean;
 };
 
 export type WorkReceiptBatchClaimCommand = {
   playName: string;
   runId: string;
   keys: string[];
+  leaseAware?: boolean;
   reclaimRunning?: boolean;
   forceRefresh?: boolean;
+  forceFailedRefresh?: boolean;
+  runAttempt?: number | null;
+  leaseTtlMs?: number | null;
 };
 
 export type WorkReceiptBatchCompleteCommand = {
   playName: string;
-  receipts: Array<{ runId: string; key: string; output: unknown }>;
+  receipts: Array<{
+    runId: string;
+    key: string;
+    output: unknown;
+    leaseId?: string | null;
+    runAttempt?: number | null;
+  }>;
 };
 
 export type WorkReceiptBatchFailCommand = {
   playName: string;
-  receipts: Array<{ runId: string; key: string; error: string }>;
+  receipts: Array<{
+    runId: string;
+    key: string;
+    error: string;
+    failureKind?: WorkReceiptFailureKind | null;
+    leaseId?: string | null;
+    runAttempt?: number | null;
+  }>;
+};
+
+export type WorkReceiptBatchHeartbeatCommand = {
+  playName: string;
+  runId: string;
+  runAttempt?: number | null;
+  leaseId: string;
+  keys: string[];
+  leaseTtlMs?: number | null;
 };
 
 export type WorkReceiptGetCommand = {
@@ -58,6 +120,10 @@ export type WorkReceiptClaim =
       disposition: 'running';
       receipt: WorkReceipt;
     }
+  | {
+      disposition: 'blocked_active_lease';
+      receipt: WorkReceipt;
+    }
   | {
       disposition: 'failed';
       receipt: WorkReceipt;
@@ -74,11 +140,22 @@ export type WorkReceiptStore = {
   ): Promise<WorkReceipt | null>;
   completeReceipts?(
     input: WorkReceiptBatchCompleteCommand,
-  ): Promise<WorkReceipt[]>;
+  ): Promise<Array<WorkReceipt | null>>;
   failReceipt(
-    input: WorkReceiptCommand & { error: string },
+    input: WorkReceiptCommand & {
+      error: string;
+      failureKind?: WorkReceiptFailureKind | null;
+    },
+  ): Promise<WorkReceipt | null>;
+  failReceipts?(
+    input: WorkReceiptBatchFailCommand,
+  ): Promise<Array<WorkReceipt | null>>;
+  releaseReceipt?(
+    input: WorkReceiptCommand,
   ): Promise<WorkReceipt | null>;
-  failReceipts?(input: WorkReceiptBatchFailCommand): Promise<WorkReceipt[]>;
+  heartbeatReceipts?(
+    input: WorkReceiptBatchHeartbeatCommand,
+  ): Promise<Array<WorkReceipt | null>>;
 };
 
 const SCOPED_WORK_RECEIPT_KEY_VERSION = 'ctxv2';
@@ -122,5 +199,5 @@ export function scopedWorkReceiptKeyPrefix(input: {
 }
 
 export function isReusableWorkReceipt(receipt: WorkReceipt): boolean {
-  return receipt.status === 'completed' || receipt.status === 'skipped';
+  return isReusableWorkReceiptState(receipt);
 }

package/dist/bundling-sources/shared_libs/plays/bundling/index.ts

@@ -475,7 +475,9 @@ export function extractDefinedPlayDescriptionForExport(
   sourceCode: string,
   exportName: string,
 ): string | null {
-  return extractDefinedPlayMetadata(sourceCode, exportName)?.description ?? null;
+  return (
+    extractDefinedPlayMetadata(sourceCode, exportName)?.description ?? null
+  );
 }
 
 type AstNode = {
@@ -548,7 +550,9 @@ function astArray(value: unknown): AstNode[] {
   return Array.isArray(value) ? value.filter(isAstNode) : [];
 }
 
-function memberExpressionPath(node: AstNode | null | undefined): string[] | null {
+function memberExpressionPath(
+  node: AstNode | null | undefined,
+): string[] | null {
   const expression = unwrapStaticExpression(node);
   if (!expression) return null;
   if (expression.type === 'Identifier' && typeof expression.name === 'string') {
@@ -657,7 +661,9 @@ function buildPlayMetadataContext(ast: AstNode): PlayMetadataExtractionContext {
         isAstNode(statement.declaration) &&
         statement.declaration.type === 'VariableDeclaration'
       ) {
-        for (const declaration of astArray(statement.declaration.declarations)) {
+        for (const declaration of astArray(
+          statement.declaration.declarations,
+        )) {
           const name = getIdentifierName(declaration.id);
           if (!name) continue;
           const initializer = isAstNode(declaration.init)
@@ -708,7 +714,9 @@ function buildPlayMetadataContext(ast: AstNode): PlayMetadataExtractionContext {
   return { declarations, namedExports, commonJsExports, defaultExport };
 }
 
-function unwrapStaticExpression(node: AstNode | null | undefined): AstNode | null {
+function unwrapStaticExpression(
+  node: AstNode | null | undefined,
+): AstNode | null {
   let current = node ?? null;
   while (
     current &&
@@ -837,9 +845,7 @@ function stringPropertyFromObjectExpression(
 
     if (property.type !== 'Property') continue;
     if (propertyNameFromKey(property) !== propertyName) continue;
-    const propertyValue = property.shorthand
-      ? property.key
-      : property.value;
+    const propertyValue = property.shorthand ? property.key : property.value;
     value = staticStringFromExpression(
       isAstNode(propertyValue) ? propertyValue : null,
       context,
@@ -883,11 +889,16 @@ function playMetadataFromDefinePlayCall(
 
   const args = astArray(expression.arguments);
   const firstArg = args[0] ?? null;
-  const objectName = stringPropertyFromObjectExpression(firstArg, 'id', context);
+  const objectName = stringPropertyFromObjectExpression(
+    firstArg,
+    'id',
+    context,
+  );
   const name = objectName ?? staticStringFromExpression(firstArg, context);
 
   let description =
-    stringPropertyFromObjectExpression(firstArg, 'description', context) ?? null;
+    stringPropertyFromObjectExpression(firstArg, 'description', context) ??
+    null;
   for (let index = args.length - 1; !description && index >= 2; index -= 1) {
     description = stringPropertyFromObjectExpression(
       args[index],
@@ -1608,7 +1619,10 @@ async function analyzeSourceGraph(
     }
     visited.add(absolutePath);
 
-    const sourceCode = await readFile(absolutePath, 'utf-8');
+    const sourceCode = await readFile(
+      /* turbopackIgnore: true */ absolutePath,
+      'utf-8',
+    );
     localFiles.set(absolutePath, sourceCode);
 
     if (extname(absolutePath).toLowerCase() === '.json') {
@@ -1645,7 +1659,10 @@ async function analyzeSourceGraph(
           column,
         });
         if (resolved !== absoluteEntryFile && isPlaySourceFile(resolved)) {
-          const importedSource = await readFile(resolved, 'utf-8');
+          const importedSource = await readFile(
+            /* turbopackIgnore: true */ resolved,
+            'utf-8',
+          );
           const importedPlayName = extractDefinedPlayName(importedSource);
           if (!importedPlayName) {
             throw new Error(