@ttt-productions/ttt-core 0.19.0 → 0.19.2

package/dist/doc-schemas/safety/case-aliases.d.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+/** Version token folded into `aliasId` and `incidentKey`. */
+export declare const SAFETY_ALIAS_VERSION = "v1";
+/** Version token folded into `correlationKey`. */
+export declare const SAFETY_CORRELATION_VERSION = "v1";
+/** Version token folded into `mergeJobId`. */
+export declare const SAFETY_MERGE_VERSION = "merge-v1";
+/** OWNING alias types — ONLY these four. (Correlation links are NEVER owning
+ * aliases; see CorrelationType below.) */
+export declare const ChildSafetyOwningAliasTypeSchema: z.ZodEnum<{
+    incidentKey: "incidentKey";
+    rootIngest: "rootIngest";
+    canonicalTarget: "canonicalTarget";
+    messageRange: "messageRange";
+}>;
+export type ChildSafetyOwningAliasType = z.infer<typeof ChildSafetyOwningAliasTypeSchema>;
+/** CORRELATION types — M:N, search/link only. NEVER select a winner, NEVER
+ * trigger a merge, NEVER live as an owning alias. */
+export declare const ChildSafetyCorrelationTypeSchema: z.ZodEnum<{
+    exactSha256: "exactSha256";
+    detectorMatch: "detectorMatch";
+}>;
+export type ChildSafetyCorrelationType = z.infer<typeof ChildSafetyCorrelationTypeSchema>;
+/** `safetyCaseMergeJobs` lifecycle status. */
+export declare const SafetyCaseMergeJobStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    complete: "complete";
+    deadLetter: "deadLetter";
+    fenced: "fenced";
+    movingLinks: "movingLinks";
+    reconcilingSubmissions: "reconcilingSubmissions";
+}>;
+export type SafetyCaseMergeJobStatus = z.infer<typeof SafetyCaseMergeJobStatusSchema>;
+export declare const ChildSafetyOwningAliasV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    caseId: z.ZodString;
+    aliasType: z.ZodEnum<{
+        incidentKey: "incidentKey";
+        rootIngest: "rootIngest";
+        canonicalTarget: "canonicalTarget";
+        messageRange: "messageRange";
+    }>;
+    canonicalValueHash: z.ZodString;
+    createdAt: z.ZodNumber;
+}, z.core.$strict>;
+export type ChildSafetyOwningAliasV1 = z.infer<typeof ChildSafetyOwningAliasV1Schema>;
+export declare const ChildSafetyCorrelationCaseV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    caseId: z.ZodString;
+    correlationType: z.ZodEnum<{
+        exactSha256: "exactSha256";
+        detectorMatch: "detectorMatch";
+    }>;
+    canonicalValueHash: z.ZodString;
+    rootIngestId: z.ZodString;
+    originatingUploaderUid: z.ZodString;
+    firstSeenAt: z.ZodNumber;
+    sourceSignalId: z.ZodString;
+}, z.core.$strict>;
+export type ChildSafetyCorrelationCaseV1 = z.infer<typeof ChildSafetyCorrelationCaseV1Schema>;
+/** A losing participant of a merge job (frozen at claim time). */
+export declare const SafetyCaseMergeLoserV1Schema: z.ZodObject<{
+    caseId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    redirectWritten: z.ZodBoolean;
+}, z.core.$strict>;
+export type SafetyCaseMergeLoserV1 = z.infer<typeof SafetyCaseMergeLoserV1Schema>;
+export declare const SafetyCaseMergeJobV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    mergeJobId: z.ZodString;
+    participantCaseIds: z.ZodArray<z.ZodString>;
+    winnerCaseId: z.ZodString;
+    mergeGeneration: z.ZodNumber;
+    losers: z.ZodArray<z.ZodObject<{
+        caseId: z.ZodString;
+        expectedRevision: z.ZodNumber;
+        redirectWritten: z.ZodBoolean;
+    }, z.core.$strict>>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        complete: "complete";
+        deadLetter: "deadLetter";
+        fenced: "fenced";
+        movingLinks: "movingLinks";
+        reconcilingSubmissions: "reconcilingSubmissions";
+    }>;
+    leaseOwner: z.ZodOptional<z.ZodString>;
+    leaseExpiresAt: z.ZodOptional<z.ZodNumber>;
+    attemptCount: z.ZodNumber;
+    nextAttemptAt: z.ZodOptional<z.ZodNumber>;
+    lastErrorCode: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SafetyCaseMergeJobV1 = z.infer<typeof SafetyCaseMergeJobV1Schema>;
+//# sourceMappingURL=case-aliases.d.ts.map

package/dist/doc-schemas/safety/case-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"case-aliases.d.ts","sourceRoot":"","sources":["../../../src/doc-schemas/safety/case-aliases.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,kDAAkD;AAClD,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAC/C,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAM/C;0CAC0C;AAC1C,eAAO,MAAM,gCAAgC;;;;;EAK3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F;qDACqD;AACrD,eAAO,MAAM,gCAAgC;;;EAA2C,CAAC;AACzF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,8CAA8C;AAC9C,eAAO,MAAM,8BAA8B;;;;;;;EAOzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAStF,eAAO,MAAM,8BAA8B;;;;;;;;;;;kBAMhC,CAAC;AACZ,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAUtF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;kBASpC,CAAC;AACZ,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAU9F,kEAAkE;AAClE,eAAO,MAAM,4BAA4B;;;;kBAI9B,CAAC;AACZ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAgB5B,CAAC;AACZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

package/dist/doc-schemas/safety/case-aliases.js

@@ -0,0 +1,110 @@
+// Trust & Safety — child-safety case ALIASES, CORRELATIONS, and MERGE (§A2,
+// Finding-H2/H3).
+//
+// The alias model is SPLIT into two disjoint structures:
+//   - OWNING aliases (1:1; the ONLY inputs to claim/merge) —
+//     `childSafetyOwningAliases/{aliasId}`.
+//   - CORRELATIONS (M:N; search/link only, NEVER inputs to claim/merge) —
+//     `childSafetyCorrelations/{correlationKey}/cases/{caseId}`.
+// A multi-case owning-alias collision spawns a deterministic, fenced merge job —
+// `safetyCaseMergeJobs/{mergeJobId}`.
+//
+// Every shape here is transcribed verbatim from docs/code_changes_needed/
+// trust-and-safety/IMPLEMENTATION_PLAN.md Appendix A §A2 — no invented values,
+// no placeholders. Deterministic IDs are documented as comments; the server
+// computes them (never this schema layer).
+import { z } from 'zod';
+// ===========================================================================
+// Canonical-key version tokens (folded into the deterministic id formulas
+// below). Bump a token if its formula input set or hashing scheme changes.
+// ===========================================================================
+/** Version token folded into `aliasId` and `incidentKey`. */
+export const SAFETY_ALIAS_VERSION = 'v1';
+/** Version token folded into `correlationKey`. */
+export const SAFETY_CORRELATION_VERSION = 'v1';
+/** Version token folded into `mergeJobId`. */
+export const SAFETY_MERGE_VERSION = 'merge-v1';
+// ===========================================================================
+// Cluster-local enums (§A2).
+// ===========================================================================
+/** OWNING alias types — ONLY these four. (Correlation links are NEVER owning
+ * aliases; see CorrelationType below.) */
+export const ChildSafetyOwningAliasTypeSchema = z.enum([
+    'incidentKey',
+    'rootIngest',
+    'canonicalTarget',
+    'messageRange',
+]);
+/** CORRELATION types — M:N, search/link only. NEVER select a winner, NEVER
+ * trigger a merge, NEVER live as an owning alias. */
+export const ChildSafetyCorrelationTypeSchema = z.enum(['exactSha256', 'detectorMatch']);
+/** `safetyCaseMergeJobs` lifecycle status. */
+export const SafetyCaseMergeJobStatusSchema = z.enum([
+    'pending',
+    'fenced',
+    'movingLinks',
+    'reconcilingSubmissions',
+    'complete',
+    'deadLetter',
+]);
+// ===========================================================================
+// §A2 — OWNING aliases: childSafetyOwningAliases/{aliasId}
+//   aliasId = sha256(SAFETY_ALIAS_VERSION + ':' + aliasType + ':' + canonicalValueHash)
+//   incidentKey = sha256('incident-v1:' + normalizedRootIngestId + ':' +
+//                        normalizedOriginatingUploaderUid)   (Finding-H3 hard key)
+// ===========================================================================
+export const ChildSafetyOwningAliasV1Schema = z.object({
+    schemaVersion: z.literal(1),
+    caseId: z.string().min(1),
+    aliasType: ChildSafetyOwningAliasTypeSchema,
+    canonicalValueHash: z.string(),
+    createdAt: z.number(),
+}).strict();
+// ===========================================================================
+// §A2 — CORRELATIONS (M:N): childSafetyCorrelations/{correlationKey}/cases/{caseId}
+//   correlationKey = sha256(SAFETY_CORRELATION_VERSION + ':' + correlationType +
+//                          ':' + canonicalValueHash)
+//   A correlation key may list many cases; the child doc is keyed by caseId.
+//   Correlations NEVER select a winner and NEVER trigger a merge.
+// ===========================================================================
+export const ChildSafetyCorrelationCaseV1Schema = z.object({
+    schemaVersion: z.literal(1),
+    caseId: z.string().min(1),
+    correlationType: ChildSafetyCorrelationTypeSchema,
+    canonicalValueHash: z.string(),
+    rootIngestId: z.string().min(1),
+    originatingUploaderUid: z.string().min(1),
+    firstSeenAt: z.number(),
+    sourceSignalId: z.string().min(1),
+}).strict();
+// ===========================================================================
+// §A2 — MERGE jobs: safetyCaseMergeJobs/{mergeJobId}
+//   mergeJobId = sha256(SAFETY_MERGE_VERSION + ':' + sortedCaseIds.join(','))
+//   (deterministic — racing workers create the same job). Winner is selected and
+//   FROZEN at merge-claim time (`mergeGeneration` stamped on every participant)
+//   and never recalculated. participantCaseIds + losers each MAX 16.
+// ===========================================================================
+/** A losing participant of a merge job (frozen at claim time). */
+export const SafetyCaseMergeLoserV1Schema = z.object({
+    caseId: z.string().min(1),
+    expectedRevision: z.number(),
+    redirectWritten: z.boolean(),
+}).strict();
+export const SafetyCaseMergeJobV1Schema = z.object({
+    schemaVersion: z.literal(1),
+    mergeJobId: z.string().min(1),
+    participantCaseIds: z.array(z.string().min(1)).max(16),
+    winnerCaseId: z.string().min(1),
+    mergeGeneration: z.number(),
+    losers: z.array(SafetyCaseMergeLoserV1Schema).max(16),
+    status: SafetyCaseMergeJobStatusSchema,
+    leaseOwner: z.string().min(1).optional(),
+    leaseExpiresAt: z.number().optional(),
+    attemptCount: z.number(),
+    nextAttemptAt: z.number().optional(),
+    lastErrorCode: z.string().min(1).optional(),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+    completedAt: z.number().optional(),
+}).strict();
+//# sourceMappingURL=case-aliases.js.map

package/dist/doc-schemas/safety/case-aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"case-aliases.js","sourceRoot":"","sources":["../../../src/doc-schemas/safety/case-aliases.ts"],"names":[],"mappings":"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"}