feat(ql3): establish 3.0 incubation baseline

2026-09-22 10:32:40 +08:00 · 2026-08-12 00:25:26 +08:00
parent 4bf92dcfeb
commit c699c32461
2817 changed files with 779642 additions and 653 deletions
@@ -0,0 +1,218 @@
+export const COMPLETION_RECEIPT_SCHEMA_VERSION = 1;
+export const MAX_COMPLETION_RECEIPT_BYTES = 4 * 1024;
+
+const RECEIPT_KEYS = [
+  'schemaVersion',
+  'runId',
+  'attemptId',
+  'callbackSequence',
+  'token',
+  'startedAtMs',
+  'finishedAtMs',
+  'exitCode',
+] as const;
+const RECEIPT_KEY_SET = new Set<string>(RECEIPT_KEYS);
+const UUID_V7_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
+
+export interface CompletionReceipt {
+  schemaVersion: typeof COMPLETION_RECEIPT_SCHEMA_VERSION;
+  runId: string;
+  attemptId: string;
+  callbackSequence: number;
+  token: string;
+  startedAtMs: number;
+  finishedAtMs: number;
+  exitCode: number;
+}
+
+export class InvalidCompletionReceiptError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidCompletionReceiptError';
+  }
+}
+
+function invalid(message: string): never {
+  throw new InvalidCompletionReceiptError(message);
+}
+
+function skipWhitespace(value: string, from: number): number {
+  let index = from;
+  while (/\s/.test(value[index] ?? '')) index += 1;
+  return index;
+}
+
+function stringEnd(value: string, from: number): number {
+  if (value[from] !== '"') invalid('Completion receipt key is not a string');
+  for (let index = from + 1; index < value.length; index += 1) {
+    if (value[index] === '\\') {
+      index += 1;
+      continue;
+    }
+    if (value[index] === '"') return index + 1;
+  }
+  return invalid('Completion receipt contains an unterminated string');
+}
+
+/** JSON.parse silently accepts duplicate keys, so reject them before parsing. */
+function assertUniqueFlatObjectKeys(value: string): void {
+  let index = skipWhitespace(value, 0);
+  if (value[index] !== '{') invalid('Completion receipt must be a JSON object');
+  index = skipWhitespace(value, index + 1);
+  const keys = new Set<string>();
+  if (value[index] === '}') return;
+
+  while (index < value.length) {
+    const keyStart = index;
+    const keyEnd = stringEnd(value, keyStart);
+    let key: string;
+    try {
+      key = JSON.parse(value.slice(keyStart, keyEnd));
+    } catch {
+      return invalid('Completion receipt contains an invalid key');
+    }
+    if (keys.has(key)) invalid('Completion receipt contains a duplicate key');
+    keys.add(key);
+
+    index = skipWhitespace(value, keyEnd);
+    if (value[index] !== ':') invalid('Completion receipt key has no value');
+    index = skipWhitespace(value, index + 1);
+    if (value[index] === '"') {
+      index = stringEnd(value, index);
+    } else {
+      if (value[index] === '{' || value[index] === '[') {
+        invalid('Completion receipt values must be scalar');
+      }
+      const valueStart = index;
+      while (
+        index < value.length &&
+        value[index] !== ',' &&
+        value[index] !== '}'
+      ) {
+        index += 1;
+      }
+      if (value.slice(valueStart, index).trim().length === 0) {
+        invalid('Completion receipt contains an empty value');
+      }
+    }
+
+    index = skipWhitespace(value, index);
+    if (value[index] === '}') return;
+    if (value[index] !== ',') invalid('Completion receipt is not a flat object');
+    index = skipWhitespace(value, index + 1);
+  }
+  invalid('Completion receipt object is incomplete');
+}
+
+export function assertCompletionReceiptId(
+  value: string,
+  field: 'runId' | 'attemptId',
+): void {
+  if (!UUID_V7_PATTERN.test(value)) {
+    invalid(`${field} must be a lowercase UUIDv7`);
+  }
+}
+
+function assertSafeTimestamp(value: unknown, field: string): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    invalid(`${field} must be a non-negative safe integer`);
+  }
+}
+
+export function validateCompletionReceipt(
+  candidate: unknown,
+): CompletionReceipt {
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    invalid('Completion receipt must be an object');
+  }
+  const record = candidate as Record<string, unknown>;
+  const keys = Object.keys(record);
+  if (
+    keys.length !== RECEIPT_KEYS.length ||
+    keys.some((key) => !RECEIPT_KEY_SET.has(key)) ||
+    RECEIPT_KEYS.some((key) => !Object.hasOwn(record, key))
+  ) {
+    invalid('Completion receipt fields do not match schema version 1');
+  }
+  if (record.schemaVersion !== COMPLETION_RECEIPT_SCHEMA_VERSION) {
+    invalid('Completion receipt schema version is unsupported');
+  }
+  if (typeof record.runId !== 'string') invalid('runId must be a string');
+  if (typeof record.attemptId !== 'string') {
+    invalid('attemptId must be a string');
+  }
+  assertCompletionReceiptId(record.runId, 'runId');
+  assertCompletionReceiptId(record.attemptId, 'attemptId');
+  if (
+    !Number.isSafeInteger(record.callbackSequence) ||
+    (record.callbackSequence as number) < 1
+  ) {
+    invalid('callbackSequence must be a positive safe integer');
+  }
+  if (typeof record.token !== 'string' || !TOKEN_PATTERN.test(record.token)) {
+    invalid('token must be a bounded base64url value');
+  }
+  assertSafeTimestamp(record.startedAtMs, 'startedAtMs');
+  assertSafeTimestamp(record.finishedAtMs, 'finishedAtMs');
+  if (record.finishedAtMs < record.startedAtMs) {
+    invalid('finishedAtMs must not be before startedAtMs');
+  }
+  if (
+    !Number.isInteger(record.exitCode) ||
+    (record.exitCode as number) < 0 ||
+    (record.exitCode as number) > 255
+  ) {
+    invalid('exitCode must be an integer between 0 and 255');
+  }
+  return {
+    schemaVersion: COMPLETION_RECEIPT_SCHEMA_VERSION,
+    runId: record.runId,
+    attemptId: record.attemptId,
+    callbackSequence: record.callbackSequence as number,
+    token: record.token,
+    startedAtMs: record.startedAtMs,
+    finishedAtMs: record.finishedAtMs,
+    exitCode: record.exitCode as number,
+  };
+}
+
+export function serializeCompletionReceipt(receipt: CompletionReceipt): string {
+  const value = validateCompletionReceipt(receipt);
+  const serialized = JSON.stringify({
+    schemaVersion: value.schemaVersion,
+    runId: value.runId,
+    attemptId: value.attemptId,
+    callbackSequence: value.callbackSequence,
+    token: value.token,
+    startedAtMs: value.startedAtMs,
+    finishedAtMs: value.finishedAtMs,
+    exitCode: value.exitCode,
+  });
+  if (Buffer.byteLength(serialized, 'utf8') > MAX_COMPLETION_RECEIPT_BYTES) {
+    invalid('Completion receipt exceeds the byte limit');
+  }
+  return serialized;
+}
+
+export function parseCompletionReceipt(
+  input: string | Uint8Array,
+): CompletionReceipt {
+  const bytes = typeof input === 'string' ? Buffer.from(input) : Buffer.from(input);
+  if (bytes.length === 0 || bytes.length > MAX_COMPLETION_RECEIPT_BYTES) {
+    invalid('Completion receipt size is outside the allowed range');
+  }
+  const value = bytes.toString('utf8');
+  if (!Buffer.from(value, 'utf8').equals(bytes)) {
+    invalid('Completion receipt must be valid UTF-8');
+  }
+  assertUniqueFlatObjectKeys(value);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return invalid('Completion receipt is not valid JSON');
+  }
+  return validateCompletionReceipt(parsed);
+}