@runeditrun/rer 0.2.77 → 0.2.78

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/README.md +32 -0
  2. package/cli/export.mjs +1 -1
  3. package/cli/portability-migrations.mjs +35 -14
  4. package/cli/portability-worker.mjs +2 -2
  5. package/cli/portability.mjs +2 -2
  6. package/global/CHANGELOG.md +8 -0
  7. package/global/README.md +32 -0
  8. package/modules/deploy-kit/owner-cli.mjs +15 -5
  9. package/modules/deploy-kit/provider.mjs +9 -4
  10. package/modules/import-kit/src/d1/README.md +1322 -0
  11. package/modules/import-kit/src/d1/apply.ts +115 -0
  12. package/modules/import-kit/src/d1/budget.ts +89 -0
  13. package/modules/import-kit/src/d1/compressed-plan.ts +63 -0
  14. package/modules/import-kit/src/d1/creation.ts +95 -0
  15. package/modules/import-kit/src/d1/custody-fence.ts +27 -0
  16. package/modules/import-kit/src/d1/custody-state-schema.ts +67 -0
  17. package/modules/import-kit/src/d1/database.ts +163 -0
  18. package/modules/import-kit/src/d1/entry-locator.ts +61 -0
  19. package/modules/import-kit/src/d1/erased-artifacts.ts +38 -0
  20. package/modules/import-kit/src/d1/erased-custody.ts +36 -0
  21. package/modules/import-kit/src/d1/erased-plan.ts +47 -0
  22. package/modules/import-kit/src/d1/erased-reversal.ts +19 -0
  23. package/modules/import-kit/src/d1/erasure-bounded.ts +22 -0
  24. package/modules/import-kit/src/d1/erasure-claims.ts +27 -0
  25. package/modules/import-kit/src/d1/erasure-compiler.ts +67 -0
  26. package/modules/import-kit/src/d1/erasure-disposition.ts +16 -0
  27. package/modules/import-kit/src/d1/erasure-fragments.ts +86 -0
  28. package/modules/import-kit/src/d1/erasure-index.ts +53 -0
  29. package/modules/import-kit/src/d1/erasure-pages.ts +62 -0
  30. package/modules/import-kit/src/d1/erasure-progress-schema.ts +8 -0
  31. package/modules/import-kit/src/d1/erasure-progress.ts +61 -0
  32. package/modules/import-kit/src/d1/erasure-related.ts +124 -0
  33. package/modules/import-kit/src/d1/erasure-report.ts +31 -0
  34. package/modules/import-kit/src/d1/erasure-schema.ts +24 -0
  35. package/modules/import-kit/src/d1/erasure-selection.ts +77 -0
  36. package/modules/import-kit/src/d1/erasure-snapshot.ts +15 -0
  37. package/modules/import-kit/src/d1/erasure-stage.ts +146 -0
  38. package/modules/import-kit/src/d1/erasure-step.ts +12 -0
  39. package/modules/import-kit/src/d1/erasure-superseded.ts +98 -0
  40. package/modules/import-kit/src/d1/erasure-values.ts +83 -0
  41. package/modules/import-kit/src/d1/erasure-writes.ts +46 -0
  42. package/modules/import-kit/src/d1/erasure.ts +170 -0
  43. package/modules/import-kit/src/d1/evolutions/0001-preserved-undo.ts +13 -0
  44. package/modules/import-kit/src/d1/expected-state.ts +91 -0
  45. package/modules/import-kit/src/d1/field-redaction.ts +86 -0
  46. package/modules/import-kit/src/d1/guards.ts +37 -0
  47. package/modules/import-kit/src/d1/history.ts +71 -0
  48. package/modules/import-kit/src/d1/index.ts +88 -0
  49. package/modules/import-kit/src/d1/integrity.ts +127 -0
  50. package/modules/import-kit/src/d1/inventory-snapshot.ts +84 -0
  51. package/modules/import-kit/src/d1/jobs.ts +97 -0
  52. package/modules/import-kit/src/d1/native-set.ts +48 -0
  53. package/modules/import-kit/src/d1/native-staging-admission.ts +19 -0
  54. package/modules/import-kit/src/d1/native-staging-context.ts +44 -0
  55. package/modules/import-kit/src/d1/native-staging-lifecycle.ts +33 -0
  56. package/modules/import-kit/src/d1/native-staging-offset.ts +74 -0
  57. package/modules/import-kit/src/d1/native-staging-publication.ts +18 -0
  58. package/modules/import-kit/src/d1/native-staging-rows.ts +72 -0
  59. package/modules/import-kit/src/d1/native-staging-schema.ts +28 -0
  60. package/modules/import-kit/src/d1/native-staging-state.ts +22 -0
  61. package/modules/import-kit/src/d1/native-staging.ts +64 -0
  62. package/modules/import-kit/src/d1/original-copies.ts +53 -0
  63. package/modules/import-kit/src/d1/original-storage.ts +56 -0
  64. package/modules/import-kit/src/d1/originals.ts +74 -0
  65. package/modules/import-kit/src/d1/plan-dictionary.ts +80 -0
  66. package/modules/import-kit/src/d1/plans.ts +121 -0
  67. package/modules/import-kit/src/d1/preparation-fingerprint.ts +57 -0
  68. package/modules/import-kit/src/d1/preparation-header.ts +33 -0
  69. package/modules/import-kit/src/d1/preparation-reader.ts +98 -0
  70. package/modules/import-kit/src/d1/preparation-schema.ts +16 -0
  71. package/modules/import-kit/src/d1/preparation-state.ts +56 -0
  72. package/modules/import-kit/src/d1/preparation-step-combine.ts +80 -0
  73. package/modules/import-kit/src/d1/preparation-step-control.ts +48 -0
  74. package/modules/import-kit/src/d1/preparation-step-hash.ts +131 -0
  75. package/modules/import-kit/src/d1/preparation-step-pages.ts +77 -0
  76. package/modules/import-kit/src/d1/preparation-steps-schema.ts +11 -0
  77. package/modules/import-kit/src/d1/preparation-steps.ts +102 -0
  78. package/modules/import-kit/src/d1/preparations.ts +87 -0
  79. package/modules/import-kit/src/d1/preserved-preview.ts +89 -0
  80. package/modules/import-kit/src/d1/preserved-reverse.ts +91 -0
  81. package/modules/import-kit/src/d1/provenance-set.ts +87 -0
  82. package/modules/import-kit/src/d1/publication-fence.ts +22 -0
  83. package/modules/import-kit/src/d1/publication-receipt-schema.ts +15 -0
  84. package/modules/import-kit/src/d1/published-stream.ts +11 -0
  85. package/modules/import-kit/src/d1/read-fence.ts +64 -0
  86. package/modules/import-kit/src/d1/read-results.ts +16 -0
  87. package/modules/import-kit/src/d1/redacted-custody.ts +76 -0
  88. package/modules/import-kit/src/d1/redaction-step.ts +125 -0
  89. package/modules/import-kit/src/d1/referenced-plans.ts +136 -0
  90. package/modules/import-kit/src/d1/retained-values.ts +35 -0
  91. package/modules/import-kit/src/d1/retirement-bounded.ts +71 -0
  92. package/modules/import-kit/src/d1/retirement-door.ts +105 -0
  93. package/modules/import-kit/src/d1/retirement-schema.ts +39 -0
  94. package/modules/import-kit/src/d1/retirement-scope.ts +94 -0
  95. package/modules/import-kit/src/d1/retirement-steps.ts +76 -0
  96. package/modules/import-kit/src/d1/retirement-tally.ts +74 -0
  97. package/modules/import-kit/src/d1/retirement.ts +136 -0
  98. package/modules/import-kit/src/d1/reversal-conversion-record.ts +19 -0
  99. package/modules/import-kit/src/d1/reversal-conversion-schema.ts +11 -0
  100. package/modules/import-kit/src/d1/reversal-conversion.ts +40 -0
  101. package/modules/import-kit/src/d1/reversal-fence-schema.ts +14 -0
  102. package/modules/import-kit/src/d1/reversal-fence.ts +106 -0
  103. package/modules/import-kit/src/d1/reversal-journal.ts +24 -0
  104. package/modules/import-kit/src/d1/reverse.ts +103 -0
  105. package/modules/import-kit/src/d1/reviewed-source.ts +23 -0
  106. package/modules/import-kit/src/d1/sets.ts +78 -0
  107. package/modules/import-kit/src/d1/staged-creation.ts +201 -0
  108. package/modules/import-kit/src/d1/staging-admission.ts +45 -0
  109. package/modules/import-kit/src/d1/staging-control.ts +43 -0
  110. package/modules/import-kit/src/d1/staging-erasure.ts +28 -0
  111. package/modules/import-kit/src/d1/staging-lifecycle.ts +49 -0
  112. package/modules/import-kit/src/d1/staging-plan.ts +15 -0
  113. package/modules/import-kit/src/d1/staging-privacy.ts +22 -0
  114. package/modules/import-kit/src/d1/staging-publication.ts +79 -0
  115. package/modules/import-kit/src/d1/staging-schema.ts +37 -0
  116. package/modules/import-kit/src/d1/staging-statements.ts +8 -0
  117. package/modules/import-kit/src/d1/staging-transport.ts +70 -0
  118. package/modules/import-kit/src/d1/stream-boundary.ts +11 -0
  119. package/modules/import-kit/src/d1/stream-create.ts +55 -0
  120. package/modules/import-kit/src/d1/stream-identity-admission.ts +37 -0
  121. package/modules/import-kit/src/d1/stream-input.ts +18 -0
  122. package/modules/import-kit/src/d1/stream-layout.ts +43 -0
  123. package/modules/import-kit/src/d1/stream-origin.ts +44 -0
  124. package/modules/import-kit/src/d1/stream-page-integrity.ts +18 -0
  125. package/modules/import-kit/src/d1/stream-partition.ts +50 -0
  126. package/modules/import-kit/src/d1/stream-plan.ts +133 -0
  127. package/modules/import-kit/src/d1/stream-receipt.ts +45 -0
  128. package/modules/import-kit/src/d1/stream-revision-schema.ts +35 -0
  129. package/modules/import-kit/src/d1/stream-snapshot.ts +26 -0
  130. package/modules/import-kit/src/d1/stream-stage.ts +79 -0
  131. package/modules/import-kit/src/d1/stream-state.ts +25 -0
  132. package/modules/import-kit/src/d1/stream-working-set.ts +30 -0
  133. package/modules/import-kit/src/d1/streams.ts +39 -0
  134. package/modules/import-kit/src/d1/target-guards.ts +9 -0
  135. package/modules/import-kit/src/d1/target-identities.ts +17 -0
  136. package/modules/import-kit/src/d1/transport.ts +10 -0
  137. package/modules/import-kit/src/d1/types.ts +162 -0
  138. package/modules/import-kit/src/d1/undo-observations.ts +39 -0
  139. package/modules/import-kit/src/d1/undo-report.ts +22 -0
  140. package/modules/import-kit/src/d1/undo-snapshot.ts +87 -0
  141. package/modules/import-kit/src/d1/undo-state.ts +84 -0
  142. package/modules/import-kit/src/d1/undo-types.ts +110 -0
  143. package/modules/import-kit/src/journal/authority.ts +12 -0
  144. package/modules/import-kit/src/plan/budget.ts +60 -0
  145. package/modules/import-kit/src/plan/index.ts +123 -0
  146. package/modules/import-kit/src/plan/size.ts +122 -0
  147. package/modules/import-kit/src/provenance/canonical-hash.ts +130 -0
  148. package/modules/import-kit/src/provenance/canonical-stream.ts +85 -0
  149. package/modules/import-kit/src/provenance/credential-names.ts +131 -0
  150. package/modules/import-kit/src/provenance/credentials.ts +317 -0
  151. package/modules/import-kit/src/provenance/identity.ts +51 -0
  152. package/modules/import-kit/src/provenance/json-snapshot.ts +21 -0
  153. package/modules/import-kit/src/provenance/resumable-sha256.ts +75 -0
  154. package/modules/import-kit/src/provenance/validate-json.ts +19 -0
  155. package/modules/import-kit/src/storage/originals.ts +87 -0
  156. package/modules/import-kit/src/storage/provenance.ts +64 -0
  157. package/modules/import-kit/src/storage/schema.ts +42 -0
  158. package/modules/import-kit/src/types.ts +47 -0
  159. package/modules/portability/README.md +98 -2
  160. package/modules/portability/backfills.mjs +42 -15
  161. package/modules/portability/ledgers.mjs +7 -1
  162. package/modules/portability/transient-tables.mjs +40 -0
  163. package/package.json +3 -1
  164. package/scripts/publish-check/reviewed.py +3 -1
@@ -0,0 +1,84 @@
1
+ import type { InventorySnapshot } from './inventory-snapshot.ts';
2
+ import { loadConversion, conversionGuards } from './reversal-conversion-record.ts';
3
+ import type { D1ReversalPolicyConversion } from './undo-types.ts';
4
+ import type { ImportJob, ImportPlan, TargetRow } from '../types.ts';
5
+ import type { D1ImportContext, D1Sql } from './types.ts';
6
+ import type { D1ReversalPolicy, D1UndoDisposition, D1UndoEvidence } from './undo-types.ts';
7
+ import { canonicalJson, sha256, attachmentHash, assertNoCredentials } from '../provenance/identity.ts';
8
+ import { effectIdentity } from '../storage/provenance.ts';
9
+ import { exactRows, jsonChunks } from './sets.ts';
10
+ import { guard, sql } from './database.ts';
11
+ import { erasedDisposition, redactedEvidenceMatches } from './erasure-disposition.ts';
12
+
13
+ export const EMPTY_REVERSAL_HASH = sha256('[]');
14
+ export const policyHash = (id: string, fingerprint: string, selected: D1ReversalPolicy) => sha256(canonicalJson([id, fingerprint, selected, 'reversal-policy-v1']));
15
+ export interface ReversalState { policy: D1ReversalPolicy; binding: string | null; cursor: number; hash: string; rows: any[]; dispositions: D1UndoDisposition[]; conversion?: D1ReversalPolicyConversion; conversionHash?: string | null }
16
+ const states = new WeakMap<ImportJob, ReversalState>();
17
+ export function policy(context: Pick<D1ImportContext, 'reversalPolicy'>): D1ReversalPolicy {
18
+ const value = context.reversalPolicy ?? 'strict';
19
+ if (!['strict', 'preserve-conflicts'].includes(value)) throw new Error('INVALID_REVERSAL_POLICY');
20
+ return value;
21
+ }
22
+ export function undoEvidence(row: TargetRow | null, context: D1ImportContext): D1UndoEvidence {
23
+ if (!row) return { revision: null, valueHash: null, attachmentHash: null, ownedHash: null, ownedValue: null };
24
+ const ownedValue = context.storage.targets.ownedContent?.(structuredClone(row)) ?? { revision: row.revision, value: row.value, attachment: row.attachment ?? null };
25
+ const encoded = canonicalJson(ownedValue);
26
+ if (encoded === undefined || canonicalJson(JSON.parse(encoded)) !== encoded) throw new Error('INVALID_UNDO_OWNERSHIP');
27
+ assertNoCredentials(ownedValue);
28
+ return { revision: row.revision, valueHash: sha256(canonicalJson(row.value)), attachmentHash: attachmentHash(row.attachment), ownedHash: sha256(encoded), ownedValue };
29
+ }
30
+ export const reportHash = (rows: any[]) => sha256(canonicalJson(rows.map(r => ({ job_id: r.job_id, effect_id: r.effect_id, position: r.position, record_json: r.record_json }))));
31
+ export async function loadReversalState(raw: any, plan: ImportPlan, context: D1ImportContext, checkPolicy = true, snapshot?:InventorySnapshot, reports?: any[]): Promise<ReversalState> {
32
+ const { reversal_policy: selected, reversal_policy_hash: binding, reversal_cursor: cursor, reversal_hash: hash } = raw;
33
+ if (!['strict', 'preserve-conflicts'].includes(selected) || !Number.isSafeInteger(cursor) || cursor < 0 || typeof hash !== 'string') throw new Error('IMPORT_REVERSAL_INTEGRITY');
34
+ if (binding === null ? selected !== 'strict' : binding !== policyHash(raw.id, raw.fingerprint, selected)) throw new Error('IMPORT_REVERSAL_INTEGRITY');
35
+ if (checkPolicy && context.reversalPolicy !== undefined && policy(context) !== selected) throw new Error('REVERSAL_POLICY_CONFLICT');
36
+ const conversion = await loadConversion(raw, context);
37
+ if (selected === 'strict') {
38
+ if (cursor !== 0 || hash !== EMPTY_REVERSAL_HASH || snapshot?.tables.has('ik_d1_reversal_reports') && snapshot.rows('ik_d1_reversal_reports','job_id',[raw.id]).length !== 0) throw new Error('IMPORT_REVERSAL_INTEGRITY');
39
+ return { policy: selected, binding, cursor, hash, rows: [], dispositions: [], conversionHash: raw.reversal_conversion_hash };
40
+ }
41
+ const results=reports??(snapshot?.tables.has('ik_d1_reversal_reports')?snapshot.rows('ik_d1_reversal_reports','job_id',[raw.id]).sort((a,b)=>a.position-b.position):(await context.storage.database.prepare('SELECT r.*,p.reversed AS native_reversed FROM ik_d1_reversal_reports r LEFT JOIN ik_provenance p ON p.id=r.effect_id AND p.job_id=r.job_id WHERE r.job_id=? ORDER BY r.position').bind(raw.id).all()).results);
42
+ if (results.length !== cursor || reportHash(results) !== hash) throw new Error('IMPORT_REVERSAL_INTEGRITY');
43
+ const expected = new Map(plan.entries.flatMap(entry => entry.effects.map((effect, index) => [effectIdentity(raw.id, entry.identity, index), { destination: plan.destination, targetKind: effect.targetKind, targetId: effect.targetId, revision: sha256(canonicalJson([raw.id, entry.identity, index, 'applied'])), value: effect.value, ...(effect.attachment ? { attachment: effect.attachment } : {}) } as TargetRow] as const)));
44
+ const dispositions = results.map((row, index) => {
45
+ let d: D1UndoDisposition;
46
+ try { d = JSON.parse(row.record_json); } catch { throw new Error('IMPORT_REVERSAL_INTEGRITY'); }
47
+ if (d?.redacted === 'erased') {
48
+ const entry = plan.entries.find(entry => entry.erased && entry.identity === d.sourceIdentity);
49
+ if (!entry || row.position !== index || d.jobId !== raw.id || d.effectId !== row.effect_id || d.effectId !== effectIdentity(raw.id, entry.identity, 0) || row.native_reversed !== null || !['reversed','retained'].includes(d.disposition) || (d.disposition === 'reversed' ? d.reason !== 'unchanged' : !['edited','dependency','superseded'].includes(d.reason)) || canonicalJson(d) !== canonicalJson(erasedDisposition(d, entry.identity))) throw new Error('IMPORT_REVERSAL_INTEGRITY');
50
+ return d;
51
+ }
52
+ const applied = expected.get(row.effect_id);
53
+ if (!d || !applied || row.position !== index || d.jobId !== raw.id || d.effectId !== row.effect_id || d.redacted !== 'evidence' && (d.targetKind !== applied.targetKind || d.targetId !== applied.targetId) || !d.entity || typeof d.entity.table !== 'string' || typeof d.entity.recordId !== 'string' || !Array.isArray(d.protectedBy) || !['reversed','retained'].includes(d.disposition) || (d.disposition === 'reversed' ? d.reason !== 'unchanged' || row.native_reversed !== 1 : d.reason === 'superseded' ? row.native_reversed !== 1 || d.protectedBy.length !== 0 : !['edited','dependency'].includes(d.reason) || row.native_reversed !== 0) || !d.observed || (d.redacted === 'evidence' ? !redactedEvidenceMatches(d) : d.redacted !== undefined || canonicalJson(d.expected) !== canonicalJson(undoEvidence(applied, context)) || d.observed.ownedHash !== null && d.observed.ownedHash !== sha256(canonicalJson(d.observed.ownedValue))) || (d.reason === 'dependency' && !d.protectedBy.length)) throw new Error('IMPORT_REVERSAL_INTEGRITY');
54
+ return d;
55
+ });
56
+ if (!['undoing','undone','rolling_back','rolled_back'].includes(raw.state) && cursor !== 0) throw new Error('IMPORT_REVERSAL_INTEGRITY');
57
+ return { policy: selected, binding, cursor, hash, rows: results, dispositions, conversionHash: raw.reversal_conversion_hash, ...(conversion ? { conversion } : {}) };
58
+ }
59
+ export function attachReversal(job: ImportJob, state: ReversalState): void { states.set(job, state); }
60
+ export function reversalState(job: ImportJob): ReversalState {
61
+ const state = states.get(job);
62
+ if (!state) throw new Error('IMPORT_REVERSAL_INTEGRITY');
63
+ return state;
64
+ }
65
+ export function reversalGuards(id: string, state: ReversalState): D1Sql[] {
66
+ return [...(state.conversionHash !== undefined || state.conversion ? conversionGuards(id, state.conversion) : []), guard(sql('EXISTS(SELECT 1 FROM ik_jobs WHERE id=? AND reversal_policy=? AND reversal_policy_hash IS ? AND reversal_cursor=? AND reversal_hash=?)', id, state.policy, state.binding, state.cursor, state.hash)),
67
+ ...exactRows('ik_d1_reversal_reports', ['job_id','effect_id','position','record_json'], state.rows, sql('job_id=?', id), undefined, undefined, {key:'job_id',values:[id]}),
68
+ // Every disposition still requires its exact native provenance state. One
69
+ // JSON snapshot per byte-bounded chunk avoids a three-bind predicate for
70
+ // every previously published effect in all later undo/report requests.
71
+ // The report's exact rows and scoped count close the disposition set;
72
+ // pending provenance belongs to the separately fenced full inventory.
73
+ ...jsonChunks(state.dispositions.filter(d => d.redacted !== 'erased').map(d => [d.effectId, id, Number(d.disposition === 'reversed' || d.reason === 'superseded')])).map(chunk => guard(sql(
74
+ "NOT EXISTS(SELECT 1 FROM json_each(?) e WHERE NOT EXISTS(SELECT 1 FROM ik_provenance p WHERE p.id IS json_extract(e.value,'$[0]') AND typeof(p.id)=typeof(json_extract(e.value,'$[0]')) AND p.job_id IS json_extract(e.value,'$[1]') AND typeof(p.job_id)=typeof(json_extract(e.value,'$[1]')) AND p.reversed IS json_extract(e.value,'$[2]') AND typeof(p.reversed)=typeof(json_extract(e.value,'$[2]'))))", chunk)))];
75
+ }
76
+
77
+ /** A pre-read monotonic revision fences already validated report bytes without
78
+ * copying their private cross-effect evidence into another transport store. */
79
+ export function snapshotReversalGuards(raw:any,state:ReversalState):D1Sql[]{
80
+ if(!Number.isSafeInteger(raw.state_revision))throw new Error('IMPORT_CUSTODY_STATE_REQUIRED');
81
+ const fence=guard(sql('EXISTS(SELECT 1 FROM ik_d1_custody_states WHERE job_id=? AND revision=?)',raw.id,raw.state_revision));
82
+ fence.expectedSnapshots=reversalGuards(raw.id,state).flatMap(row=>row.expectedSnapshots??[]);
83
+ return [fence];
84
+ }
@@ -0,0 +1,110 @@
1
+ import type { Json, TargetRow, ImportJob } from '../types.ts';
2
+ import type { D1Database, D1Sql, D1ProvenanceRow } from './types.ts';
3
+
4
+ export type D1ReversalPolicy = 'strict' | 'preserve-conflicts';
5
+ export interface D1UndoEntity { table: string; recordId: string; field?: string; targetId?: string }
6
+ export interface D1UndoEffect {
7
+ provenance: D1ProvenanceRow;
8
+ /** Immutable applied snapshot reconstructed by Kit from the reviewed plan. */
9
+ expected: TargetRow;
10
+ /** A previous batch made its retention terminal. */
11
+ retained: boolean;
12
+ }
13
+ export interface D1UndoObservation {
14
+ effectId: string;
15
+ current: TargetRow | null;
16
+ entity: D1UndoEntity;
17
+ /** Optional exact observation predicate for domain absence with retained
18
+ * ownership markers. Otherwise Kit uses targets.matches(current,...). */
19
+ guard?: D1Sql;
20
+ /** Domain evidence, e.g. the named native field and required relation rule. */
21
+ evidence?: Json;
22
+ }
23
+ export interface D1UndoDependency {
24
+ /** This effect must survive while the dependent survives, and must reverse
25
+ * AFTER that dependent. Omit dependentEffectId for a live outside dependency. */
26
+ requiredEffectId: string;
27
+ dependentEffectId?: string;
28
+ /** false makes this a retention-only edge (e.g. required MANY validity). */
29
+ order?: false;
30
+ cause: D1UndoEntity;
31
+ evidence: Json;
32
+ }
33
+ export interface D1UndoSnapshot {
34
+ observations: D1UndoObservation[];
35
+ /** Optional complete destination set from targets.list, including unrelated
36
+ * rows. Kit checks every current observation against this set (null means
37
+ * absent), then fences it through targets.matchesMany. This requires that
38
+ * adapter method; it does not replace custom observation/dependency guards. */
39
+ nativeRows?: TargetRow[];
40
+ dependencies: D1UndoDependency[];
41
+ /** Domain-required atomic reversal units, e.g. required MANY owner + joins.
42
+ * Overlapping groups are united. Retaining any member retains the unit. */
43
+ atomicGroups?: string[][];
44
+ /** Nonempty scalar predicates fencing the WHOLE observed native/dependency
45
+ * set, including absent/incoming edges and cardinalities. No mutations. */
46
+ guards: D1Sql[];
47
+ }
48
+ export interface D1PreservedUndoAdapter {
49
+ preparePreservedUndo(database: D1Database, destination: string, effects: D1UndoEffect[]): Promise<D1UndoSnapshot>;
50
+ /** Pure ownership projection applied by Kit to BOTH expected and current
51
+ * snapshots. May exclude unrelated shared revisions/fields. Never omit an
52
+ * owned value, attachment or owned revision. Full snapshots remain guarded. */
53
+ ownedContent?(row: TargetRow): Json;
54
+ }
55
+ export interface D1UndoEvidence {
56
+ revision: string | null;
57
+ valueHash: string | null;
58
+ attachmentHash: string | null;
59
+ ownedHash: string | null;
60
+ ownedValue: Json;
61
+ }
62
+ export interface D1UndoDisposition {
63
+ /** Privacy redaction preserves the disposition while removing personal
64
+ * evidence. An erased entity is identified only by its source digest. */
65
+ redacted?: 'erased' | 'evidence';
66
+ sourceIdentity?: string;
67
+ jobId: string;
68
+ effectId: string;
69
+ targetKind: string;
70
+ targetId: string;
71
+ entity: D1UndoEntity;
72
+ disposition: 'reversed' | 'retained';
73
+ /** 'superseded': a later import's effect over it was kept for the owner, so
74
+ * it can never be restored; it is reversed in provenance and kept. */
75
+ reason: 'unchanged' | 'edited' | 'dependency' | 'superseded';
76
+ expected: D1UndoEvidence;
77
+ observed: D1UndoEvidence;
78
+ protectedBy: D1UndoDependency[];
79
+ evidence: Json;
80
+ }
81
+ export interface D1UndoReport {
82
+ job: ImportJob;
83
+ policy: D1ReversalPolicy;
84
+ cursor: number;
85
+ total: number;
86
+ nextOffset: number | null;
87
+ dispositions: D1UndoDisposition[];
88
+ conversion?: D1ReversalPolicyConversion;
89
+ /** Engine state is a progress checkpoint; retained effects mean compensated. */
90
+ outcome: 'pending' | 'undone' | 'compensated';
91
+ }
92
+ export interface D1ReversalPolicyConversion {
93
+ jobId: string;
94
+ jobFingerprint: string;
95
+ from: 'strict';
96
+ to: 'preserve-conflicts';
97
+ state: 'completed' | 'undoing';
98
+ fence: number;
99
+ actorDigest: string;
100
+ recordedAt: string;
101
+ reviewedFingerprint: string;
102
+ policyHash: string;
103
+ previouslyReversed: number;
104
+ }
105
+ export interface D1PreservedUndoPreview {
106
+ job: ImportJob;
107
+ policy: D1ReversalPolicy;
108
+ reviewedFingerprint: string;
109
+ dispositions: D1UndoDisposition[];
110
+ }
@@ -0,0 +1,12 @@
1
+ import type { ImportAction, ImportContext, ImportJob } from '../types.ts';
2
+ import { requireText } from '../provenance/identity.ts';
3
+ export function authorize(context: ImportContext, action: ImportAction): void {
4
+ requireText(context.destination, 'destination'); requireText(context.namespace, 'namespace'); requireText(context.mappingVersion, 'mappingVersion'); requireText(context.authorization?.principalId, 'principalId');
5
+ const result = context.authorization.assertAuthorized(action, context.destination, context.storage.database) as unknown;
6
+ if (result && typeof (result as Promise<unknown>).then === 'function') throw new Error('ASYNC_AUTHORIZATION_FORBIDDEN');
7
+ if (result === false) throw new Error('NOT_AUTHORIZED');
8
+ }
9
+ export function bindJob(job: ImportJob, context: ImportContext): void {
10
+ if (job.destination !== context.destination || job.namespace !== context.namespace || job.mappingVersion !== context.mappingVersion || job.principalId !== context.authorization.principalId) throw new Error('JOB_BINDING_MISMATCH');
11
+ if (context.reviewedFingerprint !== undefined && context.reviewedFingerprint !== job.fingerprint) throw new Error('REVIEW_FINGERPRINT_MISMATCH');
12
+ }
@@ -0,0 +1,60 @@
1
+ import type { ImportPlan } from '../types.ts';
2
+ import { assertPlanBytes, canonicalJsonBytes, checkedSizeSum, planContentBytes, StringSizeCache } from './size.ts';
3
+
4
+ type Entry = ImportPlan['entries'][number];
5
+ type Diagnostic = ImportPlan['diagnostics'][number];
6
+ /** Exact running size, including repeated source/diagnostic text, punctuation
7
+ * and changing numeric lexemes. Each appended value is measured once; no
8
+ * growing plan is encoded or rescanned to decide admission. */
9
+ export class PlanSizeBudget {
10
+ private bytes: number;
11
+ private readonly strings = new StringSizeCache();
12
+ private kinds = 0;
13
+ private plan: ImportPlan;
14
+ constructor(plan: ImportPlan) {
15
+ this.plan = plan;
16
+ this.bytes = planContentBytes(plan, this.strings);
17
+ this.assert();
18
+ }
19
+ measure(value: unknown, sorted = false): number { return canonicalJsonBytes(value, undefined, this.strings, sorted); }
20
+ assert(): void { assertPlanBytes(this.bytes); }
21
+ private add(delta: number): void { this.bytes = checkedSizeSum(this.bytes, delta); }
22
+ replace(previousBytes: number, next: unknown): void {
23
+ this.add(checkedSizeSum(this.measure(next), -previousBytes));
24
+ }
25
+ diagnostic(item: Diagnostic): void {
26
+ this.add(checkedSizeSum(this.measure(item), Number(this.plan.diagnostics.length > 0)));
27
+ this.plan.diagnostics.push(item);
28
+ }
29
+ increment(key: Exclude<keyof ImportPlan['counts'], 'byKind'>, amount = 1): void {
30
+ const before = this.plan.counts[key];
31
+ const after = checkedSizeSum(before, amount);
32
+ this.add(checkedSizeSum(String(after).length, -String(before).length));
33
+ this.plan.counts[key] = after;
34
+ }
35
+ entry(entry: Entry): void {
36
+ this.add(checkedSizeSum(this.measure(entry), Number(this.plan.entries.length > 0)));
37
+ this.plan.entries.push(entry);
38
+ const kinds = this.plan.counts.byKind, kind = entry.source.kind, previous = kinds[kind];
39
+ const next = checkedSizeSum(previous ?? 0, 1);
40
+ if (previous === undefined) {
41
+ this.add(checkedSizeSum(this.measure(kind), this.kinds > 0 ? 3 : 2));
42
+ this.kinds = checkedSizeSum(this.kinds, 1);
43
+ } else this.add(checkedSizeSum(String(next).length, -String(previous).length));
44
+ kinds[kind] = next;
45
+ this.increment('unique');
46
+ }
47
+ mapping(entry: Entry, effects: Entry['effects'], unmapped: Entry['unmapped'], rejection?: string): void {
48
+ // A new entry starts with empty arrays; its source is already reserved.
49
+ this.add(checkedSizeSum(this.measure(effects), -2));
50
+ this.add(checkedSizeSum(this.measure(unmapped), -2));
51
+ entry.effects = effects; entry.unmapped = unmapped;
52
+ if (rejection) {
53
+ this.add(checkedSizeSum(checkedSizeSum(this.measure('rejection'), 2), this.measure(rejection)));
54
+ entry.rejection = rejection; this.increment('rejected');
55
+ }
56
+ if (effects.length) this.increment('mapped');
57
+ if (unmapped.length) this.increment('unmapped');
58
+ this.increment('effects', effects.length);
59
+ }
60
+ }
@@ -0,0 +1,123 @@
1
+ import type { ImportContext, ImportMapping, ImportPlan, SourceBundle, TargetEffect, PlanEntry } from '../types.ts';
2
+ import { canonicalJson, sourceIdentity, targetIdentity, requireText, assertNoCredentials, attachmentHash } from '../provenance/identity.ts';
3
+ import { authorize } from '../journal/authority.ts';
4
+ import { validateArtifactOriginal } from '../storage/originals.ts';
5
+ import { assertPlanSize, assertSourceSize } from './size.ts';
6
+ import { PlanSizeBudget } from './budget.ts';
7
+ import { canonicalHash, cloneJson } from '../provenance/canonical-stream.ts';
8
+ import { validateJson } from '../provenance/validate-json.ts';
9
+ import { snapshotJson } from '../provenance/json-snapshot.ts';
10
+ import { createCanonicalHasher } from '../provenance/canonical-hash.ts';
11
+
12
+ export const planFingerprint = (plan: ImportPlan): string => {
13
+ const { fingerprint: _fingerprint, ...content } = plan;
14
+ return canonicalHash(content);
15
+ };
16
+ export function validateEffect(effect: TargetEffect): void {
17
+ requireText(effect.targetKind, 'targetKind'); requireText(effect.targetId, 'targetId');
18
+ validateJson(effect.value); attachmentHash(effect.attachment);
19
+ if (effect.expectedRevision !== undefined) requireText(effect.expectedRevision, 'expectedRevision');
20
+ if (/(^|[_-])(grant|grants|job|jobs|dispatch|outbox|session|sessions|credential|credentials)([_-]|$)/i.test(effect.targetKind)) throw new Error('ACTIVE_EFFECT_FORBIDDEN');
21
+ if (/(^|[_-])(operator|operators|principal|principals|user|users|member|members|account|accounts|contact|contacts)([_-]|$)/i.test(effect.targetKind) && effect.value && typeof effect.value === 'object' && !Array.isArray(effect.value)) {
22
+ for (const [key, value] of Object.entries(effect.value)) {
23
+ if (/^(active|enabled|verified|can_administrate|canAdministrate|can_send|canSend)$/i.test(key) && value !== false && value !== 0 && value !== null) throw new Error('ACTIVE_EFFECT_FORBIDDEN');
24
+ }
25
+ }
26
+ }
27
+ export function planImport(source: SourceBundle, mapping: ImportMapping, context: ImportContext): ImportPlan {
28
+ authorize(context, 'plan');
29
+ return buildImportPlan(source, mapping, context);
30
+ }
31
+ /** Pure validated planner shared by independently authorized storage ports. */
32
+ type PlanningContext = Pick<ImportContext, 'destination' | 'namespace' | 'mappingVersion'> & { authorization: { principalId: string } };
33
+ export function buildImportPlan(source: SourceBundle, mapping: ImportMapping, context: PlanningContext): ImportPlan {
34
+ return buildPlan(source, mapping, context, value => JSON.parse(canonicalJson(value)) as SourceBundle);
35
+ }
36
+ /** Stream pages preserve independent containers while sharing immutable text.
37
+ * Ordinary eager planning keeps its established canonical source-copy contract. */
38
+ export function buildStreamPagePlan(source: SourceBundle, mapping: ImportMapping, context: PlanningContext): ImportPlan {
39
+ return buildPlan(source, mapping, context, cloneJson);
40
+ }
41
+ function buildPlan(source: SourceBundle, mapping: ImportMapping, context: PlanningContext, copySource: (source: SourceBundle) => SourceBundle): ImportPlan {
42
+ const payloadHasher = createCanonicalHasher();
43
+ try { return buildPlanWithHasher(source, mapping, context, copySource, payloadHasher.hash); }
44
+ finally { payloadHasher.clear(); }
45
+ }
46
+ function buildPlanWithHasher(source: SourceBundle, mapping: ImportMapping, context: PlanningContext, copySource: (source: SourceBundle) => SourceBundle, hashPayload: typeof canonicalHash): ImportPlan {
47
+ requireText(mapping.version, 'mapping version');
48
+ if (mapping.version !== context.mappingVersion) throw new Error('MAPPING_VERSION_MISMATCH');
49
+ assertSourceSize(source);
50
+ const plan: ImportPlan = { version: 1, destination: context.destination, namespace: context.namespace, mappingVersion: mapping.version, principalId: context.authorization.principalId, source, entries: [], diagnostics: source.diagnostics, counts: { input: source.records.length, unique: 0, duplicates: 0, mapped: 0, unmapped: 0, rejected: 0, effects: 0, byKind: Object.create(null) }, fingerprint: '' };
51
+ // Source diagnostics are persisted twice. Admit the initial plan before
52
+ // encoding or copying any of the source, including caller metadata.
53
+ const budget = new PlanSizeBudget(plan);
54
+ assertNoCredentials(source, source.paginationCursorPolicy);
55
+ const copy = copySource(source);
56
+ plan.source = copy; plan.diagnostics = [...copy.diagnostics];
57
+ const seen = new Map<string, string>(), targets = new Set<string>();
58
+ const artifacts = new Set<string>();
59
+ for (const artifact of copy.artifacts) {
60
+ requireText(artifact.name, 'artifact name');
61
+ if (!/^[a-f0-9]{64}$/.test(artifact.sha256) || !Number.isSafeInteger(artifact.size) || artifact.size < 0) throw new Error('INVALID_ARTIFACT');
62
+ const key = canonicalJson([artifact.name, artifact.sha256]);
63
+ if (artifacts.has(key)) throw new Error('DUPLICATE_ARTIFACT');
64
+ artifacts.add(key);
65
+ const previousBytes = budget.measure(artifact);
66
+ if (!artifact.original) artifact.original = { status: 'unavailable', reason: 'not-supplied' };
67
+ if (artifact.original.status === 'unavailable') budget.diagnostic({ severity: 'warning', code: 'ORIGINAL_UNAVAILABLE', message: (artifact.original.reason === 'credentials-removed' ? 'Exact original bytes were withheld because they held credential values: ' : 'Exact original bytes were not supplied for ') + artifact.name });
68
+ budget.replace(previousBytes, artifact); budget.assert();
69
+ validateArtifactOriginal(artifact, copy.paginationCursorPolicy);
70
+ }
71
+ for (const sourceRecord of copy.records) {
72
+ requireText(sourceRecord.kind, 'kind'); requireText(sourceRecord.sourceId, 'sourceId'); requireText(sourceRecord.location?.artifact, 'source location');
73
+ if (sourceRecord.namespace !== context.namespace) throw new Error('SOURCE_NAMESPACE_MISMATCH');
74
+ const validatePayload = () => { if (hashPayload(sourceRecord.payload) !== sourceRecord.payloadHash) throw new Error('SOURCE_HASH_MISMATCH'); };
75
+ if (!copy.artifacts.some(artifact => artifact.sha256 === sourceRecord.artifactHash && artifact.name === sourceRecord.location.artifact)) throw new Error('SOURCE_ARTIFACT_MISSING');
76
+ const identity = sourceIdentity(context.destination, context.namespace, sourceRecord.kind, sourceRecord.sourceId);
77
+ if (seen.has(identity)) {
78
+ validatePayload();
79
+ if (seen.get(identity) !== sourceRecord.payloadHash) throw new Error('DUPLICATE_SOURCE_CONFLICT');
80
+ budget.increment('duplicates');
81
+ budget.diagnostic({ severity: 'warning', code: 'DUPLICATE_SOURCE', message: 'Identical source identity collapsed.', kind: sourceRecord.kind, sourceId: sourceRecord.sourceId, location: sourceRecord.location });
82
+ budget.assert();
83
+ continue;
84
+ }
85
+ // Reserve the second persisted occurrence of source before payload
86
+ // encoding or the mapper-input clone. Identity components are bounded IDs.
87
+ const entry: PlanEntry = { source: sourceRecord, identity, effects: [], unmapped: [] };
88
+ budget.entry(entry); budget.assert();
89
+ validatePayload();
90
+ seen.set(identity, sourceRecord.payloadHash);
91
+ const mapped = snapshotJson(mapping.map(cloneJson(sourceRecord)));
92
+ // Validate durable values without serializing the mapper's expansion.
93
+ budget.measure(mapped, true);
94
+ if (!Array.isArray(mapped.effects)) throw new Error('INVALID_MAPPING');
95
+ if (mapped.effects.length > 1000) throw new Error('SOURCE_EFFECT_LIMIT');
96
+ if (mapped.rejection && mapped.effects.length) throw new Error('REJECTED_RECORD_HAS_EFFECTS');
97
+ const unmapped = !mapped.effects.length && !mapped.rejection && !mapped.unmapped?.length
98
+ ? [{ reason: 'Source object has no native mapping; parsed record retained. Original availability is reported separately.' }]
99
+ : mapped.unmapped ?? [];
100
+ budget.mapping(entry, mapped.effects, unmapped, mapped.rejection);
101
+ for (const item of unmapped) budget.diagnostic({ severity: 'warning', code: 'UNMAPPED', message: item.reason, kind: sourceRecord.kind, sourceId: sourceRecord.sourceId, location: sourceRecord.location, ...(item.field ? { field: item.field } : {}) });
102
+ if (mapped.rejection) budget.diagnostic({ severity: 'error', code: 'REJECTED', message: mapped.rejection, kind: sourceRecord.kind, sourceId: sourceRecord.sourceId, location: sourceRecord.location });
103
+ // Includes all repeated fields and cumulative mappings, before cloning,
104
+ // effect validation (attachment decoding), or target identity encoding.
105
+ budget.assert();
106
+ for (const item of unmapped) requireText(item.reason, 'unmapped reason');
107
+ assertNoCredentials(mapped);
108
+ const effects = cloneJson(mapped.effects);
109
+ entry.effects = effects;
110
+ entry.unmapped = cloneJson(unmapped);
111
+ for (const effect of effects) {
112
+ validateEffect(effect);
113
+ const key = targetIdentity(context.destination, effect.targetKind, effect.targetId);
114
+ if (targets.has(key)) throw new Error('DUPLICATE_TARGET');
115
+ targets.add(key);
116
+ }
117
+
118
+ }
119
+ plan.counts.byKind = JSON.parse(canonicalJson(plan.counts.byKind));
120
+ assertPlanSize(plan);
121
+ plan.fingerprint = planFingerprint(plan);
122
+ return plan;
123
+ }
@@ -0,0 +1,122 @@
1
+ import type { ImportPlan, SourceBundle } from '../types.ts';
2
+
3
+ /**
4
+ * Largest accepted import plan, in UTF-8 bytes of the canonical JSON the
5
+ * fingerprint and every storage port encode (the plan without its
6
+ * `fingerprint` field). See README "Plan-size cap" for the measurements.
7
+ */
8
+ export const PLAN_BYTES_LIMIT = 300_000_000;
9
+
10
+ /** Checked arithmetic for measured bytes and the counters that change their
11
+ * numeric lexemes. Signed deltas must stay exact as well as the final total. */
12
+ export function checkedSizeSum(a: number, b: number): number {
13
+ const total = a + b;
14
+ if (!Number.isSafeInteger(a) || !Number.isSafeInteger(b) || !Number.isSafeInteger(total)) {
15
+ throw new Error('INVALID_JSON: canonical byte size exceeds safe integer range');
16
+ }
17
+ return total;
18
+ }
19
+
20
+ /** A plan (or its source, which the plan contains) over PLAN_BYTES_LIMIT.
21
+ * `bytes` is the measured canonical size; for `subject: 'source'` it is a
22
+ * lower bound of the plan that would have been built. */
23
+ export class PlanTooLargeError extends Error {
24
+ readonly code = 'IMPORT_PLAN_TOO_LARGE';
25
+ readonly bytes: number;
26
+ readonly limit: number;
27
+ readonly subject: 'source' | 'plan';
28
+ constructor(bytes: number, limit: number, subject: 'source' | 'plan') {
29
+ super(`IMPORT_PLAN_TOO_LARGE: the import ${subject} is ${bytes} canonical JSON bytes; the limit is ${limit}`);
30
+ this.bytes = bytes; this.limit = limit; this.subject = subject;
31
+ }
32
+ }
33
+
34
+ function stringBytes(text: string): number {
35
+ let n = 2;
36
+ for (let i = 0; i < text.length; i++) {
37
+ const c = text.charCodeAt(i);
38
+ if (c === 0x22 || c === 0x5c || c === 0x08 || c === 0x09 || c === 0x0a || c === 0x0c || c === 0x0d) n += 2;
39
+ else if (c < 0x20) n += 6;
40
+ else if (c < 0x80) n += 1;
41
+ else if (c < 0x800) n += 2;
42
+ else if (c >= 0xd800 && c <= 0xdbff) {
43
+ const next = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
44
+ if (next >= 0xdc00 && next <= 0xdfff) { n += 4; i++; } else n += 6;
45
+ } else if (c >= 0xdc00 && c <= 0xdfff) n += 6;
46
+ else n += 3;
47
+ }
48
+ return checkedSizeSum(n, 0);
49
+ }
50
+
51
+ /** A planning-local cache of immutable string sizes. Both entry count and
52
+ * retained UTF-16 units are bounded; containers and property reads are never
53
+ * cached across size walks. Oversized strings are measured without retention. */
54
+ export class StringSizeCache {
55
+ private readonly sizes = new Map<string, number>();
56
+ private units = 0;
57
+ measure(text: string): number {
58
+ const previous = this.sizes.get(text);
59
+ if (previous !== undefined) return previous;
60
+ const bytes = stringBytes(text);
61
+ if (text.length <= 64 * 1024 && this.sizes.size < 4096 && this.units + text.length <= 512 * 1024) {
62
+ this.sizes.set(text, bytes); this.units += text.length;
63
+ }
64
+ return bytes;
65
+ }
66
+ }
67
+
68
+ /** UTF-8 byte length of canonicalJson(value), without building that string.
69
+ * Shared references count at every occurrence. Cycles and nesting beyond 256
70
+ * containers are rejected before the recursive encoder/credential walk runs. */
71
+ export function canonicalJsonBytes(value: unknown, skipKey?: string, strings = new StringSizeCache(), sorted = false): number {
72
+ const active = new Set<object>();
73
+ const measured = new WeakMap<object, { bytes: number; depth: number }>();
74
+ const visit = (item: unknown, depth: number, omit?: string): number => {
75
+ if (item === null) return 4;
76
+ if (typeof item === 'boolean') return item ? 4 : 5;
77
+ if (typeof item === 'string') return strings.measure(item);
78
+ if (typeof item === 'number' && Number.isFinite(item)) return JSON.stringify(item).length;
79
+ if (typeof item !== 'object' || !item || (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null)) throw new Error('INVALID_JSON: durable values must be finite JSON');
80
+ if (depth >= 256 || active.has(item)) throw new Error('INVALID_JSON: cyclic or excessively nested durable value');
81
+ // Root omission changes its shape; descendants are always counted whole.
82
+ const cached = omit === undefined ? measured.get(item) : undefined;
83
+ if (cached !== undefined && depth <= cached.depth) return cached.bytes;
84
+ active.add(item);
85
+ let n = 2;
86
+ if (Array.isArray(item)) {
87
+ for (let i = 0; i < item.length; i++) n = checkedSizeSum(n, checkedSizeSum(visit(item[i], depth + 1), i ? 1 : 0));
88
+ } else {
89
+ let first = true;
90
+ const keys = Object.keys(item);
91
+ if (sorted) keys.sort();
92
+ for (const key of keys) {
93
+ if (key === omit) continue;
94
+ const prefix = checkedSizeSum(strings.measure(key), first ? 1 : 2);
95
+ n = checkedSizeSum(n, checkedSizeSum(prefix, visit((item as Record<string, unknown>)[key], depth + 1)));
96
+ first = false;
97
+ }
98
+ }
99
+ active.delete(item);
100
+ if (omit === undefined) measured.set(item, { bytes: n, depth });
101
+ return n;
102
+ };
103
+ return visit(value, 0, skipKey);
104
+ }
105
+
106
+ export function assertPlanBytes(bytes: number): void {
107
+ checkedSizeSum(bytes, 0);
108
+ if (bytes > PLAN_BYTES_LIMIT) throw new PlanTooLargeError(bytes, PLAN_BYTES_LIMIT, 'plan');
109
+ }
110
+
111
+ /** Canonical size of the plan content the fingerprint encodes. */
112
+ export const planContentBytes = (plan: ImportPlan, strings?: StringSizeCache): number => canonicalJsonBytes(plan, 'fingerprint', strings);
113
+
114
+ /** Checked before any whole-source or whole-plan encoding. */
115
+ export function assertSourceSize(source: SourceBundle): void {
116
+ const bytes = canonicalJsonBytes(source);
117
+ if (bytes > PLAN_BYTES_LIMIT) throw new PlanTooLargeError(bytes, PLAN_BYTES_LIMIT, 'source');
118
+ }
119
+ export function assertPlanSize(plan: ImportPlan): void {
120
+ const bytes = planContentBytes(plan);
121
+ if (bytes > PLAN_BYTES_LIMIT) throw new PlanTooLargeError(bytes, PLAN_BYTES_LIMIT, 'plan');
122
+ }
@@ -0,0 +1,130 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { Buffer } from 'node:buffer';
3
+ import { jsonStringParts } from './identity.ts';
4
+ import { ResumableSha256, type Sha256State } from './resumable-sha256.ts';
5
+
6
+ const encoder = new TextEncoder();
7
+ let availableBuffer: Uint8Array | undefined;
8
+ type StringCache = { strings: Map<string, Uint8Array>; retainedBytes: number };
9
+ const stringCache = (): StringCache => ({ strings: new Map(), retainedBytes: 0 });
10
+
11
+ /** Reuse only immutable string encodings during one caller-owned operation.
12
+ * Clear in its finally block; no source containers or digests are cached. */
13
+ export function createCanonicalHasher() {
14
+ const cache = stringCache();
15
+ return {
16
+ hash: (value: unknown) => hashCanonical(value, cache),
17
+ clear() {
18
+ for (const bytes of cache.strings.values()) bytes.fill(0);
19
+ cache.strings.clear(); cache.retainedBytes = 0;
20
+ },
21
+ };
22
+ }
23
+
24
+ /** Hash exact canonical UTF-8 with a fixed output buffer. Repeated immutable
25
+ * strings share encoded bytes only within this call; object contents are
26
+ * always traversed afresh, including reads from normalized page views. */
27
+ export function canonicalHash(value: unknown): string {
28
+ return hashCanonical(value, stringCache());
29
+ }
30
+ function hashCanonical(value: unknown, cache: StringCache): string {
31
+ const writer = canonicalWriter(cache);
32
+ try { writer.value(value); return writer.digest(); }
33
+ finally { writer.release(); }
34
+ }
35
+
36
+ /** One canonical document may draw array elements from awaited custody reads.
37
+ * Containers and values still use the same writer; no object digest is reused. */
38
+ export function createCanonicalStreamHash() {
39
+ const cache = stringCache(), writer = canonicalWriter(cache);
40
+ let closed = false;
41
+ const active = () => { if (closed) throw new Error('CANONICAL_HASH_CLOSED'); };
42
+ return {
43
+ value(value: unknown) { active(); writer.value(value); },
44
+ token(value: '[' | ']' | '{' | '}' | ':' | ',') { active(); writer.token(value); },
45
+ digest() { active(); return writer.digest(); },
46
+ clear() {
47
+ if (closed) return;
48
+ closed = true; writer.release();
49
+ for (const bytes of cache.strings.values()) bytes.fill(0);
50
+ cache.strings.clear(); cache.retainedBytes = 0;
51
+ },
52
+ };
53
+ }
54
+
55
+ /** The same canonical stream hash whose state can be saved between requests:
56
+ * `checkpoint()` returns it, and `resume` continues from a saved one. Callers
57
+ * keep the saved state server-side; it fences nothing by itself. */
58
+ export function createResumableCanonicalHash(resume?: Sha256State) {
59
+ const cache = stringCache(), hash = resume ? ResumableSha256.from(resume) : new ResumableSha256(), writer = canonicalWriter(cache, hash);
60
+ return {
61
+ value(value: unknown) { writer.value(value); },
62
+ token(value: '[' | ']' | '{' | '}' | ':' | ',') { writer.token(value); },
63
+ checkpoint(): Sha256State { writer.flush(); return hash.state(); },
64
+ digest() { return writer.digest(); },
65
+ clear() { writer.release(); for (const bytes of cache.strings.values()) bytes.fill(0); cache.strings.clear(); cache.retainedBytes = 0; },
66
+ };
67
+ }
68
+
69
+ function canonicalWriter(cache: StringCache, hash: { update(bytes: Uint8Array): unknown; digest(encoding: 'hex'): string } = createHash('sha256')) {
70
+ // Hashing many small records must not allocate a new 64 KiB backing store
71
+ // for each record. A nested getter acquires its own buffer; returned scratch
72
+ // is wiped even when validation fails and retains no source bytes.
73
+ const buffer = availableBuffer ?? new Uint8Array(64 * 1024), { strings } = cache;
74
+ availableBuffer = undefined;
75
+ const cacheEntries = 4096, cacheBytes = 1024 * 1024;
76
+ let offset = 0;
77
+ const flush = () => { if (offset) hash.update(buffer.subarray(0, offset)); offset = 0; };
78
+ const byte = (value: number) => { if (offset === buffer.length) flush(); buffer[offset++] = value; };
79
+ const ascii = (text: string) => { for (let index = 0; index < text.length; index++) byte(text.charCodeAt(index)); };
80
+ const encoded = (bytes: Uint8Array) => {
81
+ if (offset + bytes.length > buffer.length) flush();
82
+ if (bytes.length >= buffer.length) hash.update(bytes);
83
+ else { buffer.set(bytes, offset); offset += bytes.length; }
84
+ };
85
+ const text = (value: string) => {
86
+ const previous = strings.get(value);
87
+ if (previous !== undefined) { encoded(previous); return; }
88
+ if (value.length > 1024 * 1024) { for (const part of jsonStringParts(value)) writeQuoted(part); return; }
89
+ const quoted = JSON.stringify(value);
90
+ if (strings.size < cacheEntries && Buffer.byteLength(quoted) <= cacheBytes - cache.retainedBytes) {
91
+ const bytes = encoder.encode(quoted);
92
+ strings.set(value, bytes); cache.retainedBytes += bytes.length; encoded(bytes); return;
93
+ }
94
+ // Large or distinct literals never grow the cache or create a second
95
+ // whole-literal byte array. encodeInto preserves complete code points.
96
+ writeQuoted(quoted);
97
+ };
98
+ const writeQuoted = (quoted: string) => {
99
+ for (let consumed = 0; consumed < quoted.length;) {
100
+ const { read, written } = encoder.encodeInto(quoted.slice(consumed), buffer.subarray(offset));
101
+ offset += written; consumed += read;
102
+ if (!read || offset === buffer.length) flush();
103
+ }
104
+ };
105
+ const visit = (item: unknown): void => {
106
+ if (item === null) { ascii('null'); return; }
107
+ if (typeof item === 'string') { text(item); return; }
108
+ if (typeof item === 'boolean') { ascii(item ? 'true' : 'false'); return; }
109
+ if (typeof item === 'number' && Number.isFinite(item)) { ascii(JSON.stringify(item)); return; }
110
+ if (Array.isArray(item)) {
111
+ byte(91);
112
+ const length = item.length;
113
+ for (let index = 0; index < length; index++) { if (index) byte(44); visit(item[index]); }
114
+ byte(93); return;
115
+ }
116
+ if (item && typeof item === 'object' && (Object.getPrototypeOf(item) === Object.prototype || Object.getPrototypeOf(item) === null)) {
117
+ byte(123); let first = true;
118
+ for (const key of Object.keys(item).sort()) { if (!first) byte(44); first = false; text(key); byte(58); visit((item as Record<string, unknown>)[key]); }
119
+ byte(125); return;
120
+ }
121
+ throw new Error('INVALID_JSON: durable values must be finite JSON');
122
+ };
123
+ return {
124
+ value: visit,
125
+ token(value: string) { if (!/^[\[\]{}:,]$/.test(value)) throw new Error('INVALID_CANONICAL_TOKEN'); byte(value.charCodeAt(0)); },
126
+ flush,
127
+ digest() { flush(); return hash.digest('hex'); },
128
+ release() { buffer.fill(0); availableBuffer ??= buffer; },
129
+ };
130
+ }