@abelxiaoxing/cadence 2.0.25 → 2.0.27

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.
@@ -23,6 +23,7 @@ import {
23
23
  retryWindowsFileOperation,
24
24
  safeDirectory,
25
25
  } from "../workspace.ts";
26
+ import { selfMark } from "./liveness.ts";
26
27
  export interface CheckoutLock {
27
28
  schema: "cadence-assistant-lock/1";
28
29
  token: string;
@@ -30,6 +31,9 @@ export interface CheckoutLock {
30
31
  host: string;
31
32
  runId: string;
32
33
  root: string;
34
+ /** Liveness marks (absent in locks written by older releases). */
35
+ boot?: string | null;
36
+ started?: string | null;
33
37
  }
34
38
  export class CheckoutStore {
35
39
  readonly root: string;
@@ -100,6 +104,7 @@ export class CheckoutStore {
100
104
  acquire(): CheckoutLock {
101
105
  this.inspectPrivate();
102
106
  safeDirectory(this.privateRoot, true);
107
+ const mark = selfMark();
103
108
  const lock: CheckoutLock = {
104
109
  schema: "cadence-assistant-lock/1",
105
110
  token: randomUUID(),
@@ -107,6 +112,8 @@ export class CheckoutStore {
107
112
  pid: process.pid,
108
113
  host: hostname(),
109
114
  root: this.root,
115
+ boot: mark.boot,
116
+ started: mark.started,
110
117
  };
111
118
  let fd: number;
112
119
  try {
@@ -46,6 +46,9 @@ export interface ModelCatalog extends ModelChoiceState {
46
46
  /** Models left out because a provider/model ID contains a known credential
47
47
  * literal or control characters; never their identifiers. */
48
48
  withheld: number;
49
+ /** The saved preference that the next Send would install, read only and
50
+ * offered only when it names a selectable entry of this catalog. */
51
+ remembered: ModelSelector | null;
49
52
  }
50
53
  export interface ChooseModelRequest {
51
54
  expected: ChoiceVersion;
@@ -120,6 +123,19 @@ export function decodeModelCandidate(value: unknown): ModelCandidate {
120
123
  invalid();
121
124
  return candidate;
122
125
  }
126
+ /** Whether a catalog offers this exact selector as a selectable choice. */
127
+ export function catalogOffers(
128
+ entries: readonly ModelCandidate[],
129
+ selector: ModelSelector,
130
+ ): boolean {
131
+ return entries.some(
132
+ (e) =>
133
+ e.provider === selector.provider &&
134
+ e.model === selector.model &&
135
+ e.api === selector.api &&
136
+ e.thinking.some((t) => t.selectable && t.level === selector.thinking),
137
+ );
138
+ }
123
139
  export function decodeModelCatalog(value: unknown): ModelCatalog {
124
140
  canonicalJson({ kind: "ok", value }, LIMITS.pageBytes);
125
141
  const o = closed(value, [
@@ -128,15 +144,18 @@ export function decodeModelCatalog(value: unknown): ModelCatalog {
128
144
  "status",
129
145
  "entries",
130
146
  "withheld",
147
+ "remembered",
131
148
  ]);
132
149
  const entries = list(o.entries, LIMITS.maxPageEntries, decodeModelCandidate);
150
+ const remembered = nullable(o.remembered, decodeModelSelector);
133
151
  const status = oneOf(o.status, ["complete", "capacity"]);
134
152
  const withheld = integer(o.withheld, 0, LIMITS.maxPageEntries);
135
153
  if (
136
154
  (status === "capacity" && (entries.length || withheld)) ||
137
155
  entries.length + withheld > LIMITS.maxPageEntries ||
138
156
  new Set(entries.map((e) => canonicalJson([e.provider, e.model]))).size !==
139
- entries.length
157
+ entries.length ||
158
+ (remembered && !catalogOffers(entries, remembered))
140
159
  )
141
160
  invalid();
142
161
  return {
@@ -145,5 +164,6 @@ export function decodeModelCatalog(value: unknown): ModelCatalog {
145
164
  status,
146
165
  entries,
147
166
  withheld,
167
+ remembered,
148
168
  };
149
169
  }
@@ -19,6 +19,12 @@ import {
19
19
  oneOf,
20
20
  text,
21
21
  } from "./contracts/core.ts";
22
+ import {
23
+ decodeMarkFields,
24
+ holderState,
25
+ selfMark,
26
+ stampTime,
27
+ } from "./liveness.ts";
22
28
  import {
23
29
  DirectoryWalks,
24
30
  encoded,
@@ -120,7 +126,7 @@ function reservation(r: Registration): Reservation {
120
126
  } = r;
121
127
  return row;
122
128
  }
123
- function decodeRegistration(value: unknown): Registration {
129
+ export function decodeRegistration(value: unknown): Registration {
124
130
  const o = closed(value, registrationKeys);
125
131
  const row = Object.fromEntries(reservationKeys.map((k) => [k, o[k]]));
126
132
  return {
@@ -156,38 +162,42 @@ interface RegistryLock {
156
162
  token: string;
157
163
  pid: number;
158
164
  host: string;
165
+ boot: string | null;
166
+ started: string | null;
167
+ }
168
+ /** Older locks lack the liveness marks; new ones carry both. */
169
+ export function markedKeys(value: unknown, keys: string[]): string[] {
170
+ const has = (key: string) =>
171
+ !!value && typeof value === "object" && Object.hasOwn(value, key);
172
+ return [
173
+ ...keys,
174
+ ...(has("boot") ? ["boot"] : []),
175
+ ...(has("started") ? ["started"] : []),
176
+ ];
159
177
  }
160
- function decodeRegistryLock(snapshot: FileSnapshot): RegistryLock {
161
- const o = closed(json(snapshot), ["schema", "token", "pid", "host"]);
178
+ export function decodeRegistryLock(snapshot: FileSnapshot): RegistryLock {
179
+ const raw = json(snapshot);
180
+ const o = closed(raw, markedKeys(raw, ["schema", "token", "pid", "host"]));
162
181
  return {
163
182
  schema: literal(o.schema, "cadence-service-registry-lock/1"),
164
183
  token: decodeId(o.token),
165
184
  // kill(0)/negative process-group probes must never be possible.
166
185
  pid: integer(o.pid, 1, 2147483647),
167
186
  host: text(o.host, 255, true),
187
+ ...decodeMarkFields(o),
168
188
  };
169
189
  }
170
190
  export interface RegistryLockDiagnostic {
171
191
  reason: "registry-locked";
172
192
  owner: "live" | "absent" | "ambiguous" | "unreadable";
173
193
  }
174
- export interface RegistryRecoveryInspection {
175
- scope: "global-registry";
176
- epoch: string; // exact lock incarnation, not a service epoch
177
- coordinationDigest: string;
178
- owner: "live" | "absent" | "ambiguous";
179
- process: { pid: number; host: string };
180
- reservations: number;
181
- previousResolver: "live" | "absent" | "ambiguous" | null;
182
- resolution: "local-interactive-only";
183
- }
184
194
  const registryNames = [
185
195
  "format.json",
186
196
  "roots.json",
187
197
  "registry.lock",
188
198
  "recovery-v1",
189
199
  ];
190
- interface RegistryView {
200
+ export interface RegistryView {
191
201
  format: FileSnapshot;
192
202
  snapshot: FileSnapshot;
193
203
  value: Registry;
@@ -202,39 +212,6 @@ interface Selected {
202
212
  checkout?: FileSnapshot;
203
213
  value?: Registration;
204
214
  }
205
- export function recoveryOwnerStatus(
206
- pid: number,
207
- host: string,
208
- ): "live" | "absent" | "ambiguous" {
209
- if (host !== hostname()) return "ambiguous";
210
- try {
211
- process.kill(pid, 0);
212
- return "live";
213
- } catch (error) {
214
- return error instanceof Error && "code" in error && error.code === "ESRCH"
215
- ? "absent"
216
- : "ambiguous";
217
- }
218
- }
219
- function recoveryDigest(registry: RegistryView, selected: Selected): string {
220
- return hash(
221
- encoded([
222
- registry.format.identity,
223
- registry.format.stamp,
224
- registry.snapshot.identity,
225
- registry.snapshot.stamp,
226
- selected.capability?.stamp ?? null, // incarnation only; never a secret-derived capability digest
227
- ...[
228
- selected.manifest,
229
- selected.config,
230
- selected.hostConfig,
231
- selected.registration,
232
- selected.owner,
233
- selected.checkout,
234
- ].map((value) => (value ? [value.identity, value.stamp] : null)),
235
- ]),
236
- );
237
- }
238
215
  export type CoordinationStatus =
239
216
  | { status: "absent" | "unavailable" }
240
217
  | {
@@ -408,13 +385,11 @@ export class ServiceCoordination {
408
385
  throw new ContractError("quarantine");
409
386
  if (value && value.phase !== "stopped") {
410
387
  if (!owner || !checkout || !capability) refused();
411
- const lock = closed(json(owner), [
412
- "schema",
413
- "epoch",
414
- "token",
415
- "pid",
416
- "host",
417
- ]);
388
+ const raw = json(owner);
389
+ const lock = closed(
390
+ raw,
391
+ markedKeys(raw, ["schema", "epoch", "token", "pid", "host"]),
392
+ );
418
393
  literal(lock.schema, "cadence-service-owner-lock/1");
419
394
  literal(lock.epoch, value.epoch);
420
395
  literal(lock.token, value.ownerToken);
@@ -496,6 +471,20 @@ export class ServiceCoordination {
496
471
  }),
497
472
  );
498
473
  }
474
+ /** Validated registry, or undefined before the first reservation. */
475
+ registryView(): RegistryView | undefined {
476
+ return this.registry();
477
+ }
478
+ /** The short exclusive registry section, for self-healing reclaims. */
479
+ mutateRegistry<T>(
480
+ operation: (
481
+ view: RegistryView,
482
+ mutate: () => void,
483
+ assertHeld: () => void,
484
+ ) => T,
485
+ ): T {
486
+ return this.withRegistry(operation);
487
+ }
499
488
  private withRegistry<T>(
500
489
  operation: (
501
490
  view: RegistryView,
@@ -508,6 +497,7 @@ export class ServiceCoordination {
508
497
  const lockPath = this.registryPath("registry.lock");
509
498
  let lock: FileSnapshot;
510
499
  try {
500
+ const mark = selfMark();
511
501
  lock = this.files.create(
512
502
  lockPath,
513
503
  encoded({
@@ -515,6 +505,8 @@ export class ServiceCoordination {
515
505
  token: randomUUID(),
516
506
  pid: process.pid,
517
507
  host: hostname(),
508
+ boot: mark.boot,
509
+ started: mark.started,
518
510
  }),
519
511
  );
520
512
  } catch (error) {
@@ -648,6 +640,7 @@ export class ServiceCoordination {
648
640
  const checkout = this.store.acquire();
649
641
  const checkoutFile = this.files.read(this.store.lockPath, 8192);
650
642
  if (!checkoutFile) refused();
643
+ const mark = selfMark();
651
644
  const owner = this.files.create(
652
645
  this.path("owner.lock"),
653
646
  encoded({
@@ -656,6 +649,8 @@ export class ServiceCoordination {
656
649
  token: row.ownerToken,
657
650
  pid: row.pid,
658
651
  host: row.host,
652
+ boot: mark.boot,
653
+ started: mark.started,
659
654
  }),
660
655
  );
661
656
  const capability = this.files.create(
@@ -758,323 +753,20 @@ export class ServiceCoordination {
758
753
  const lock = this.files.read(this.registryPath("registry.lock"));
759
754
  if (!lock) return undefined;
760
755
  const value = decodeRegistryLock(lock);
756
+ const holder = holderState(value, stampTime(lock.stamp)).state;
761
757
  return {
762
758
  reason: "registry-locked",
763
- owner: recoveryOwnerStatus(value.pid, value.host),
759
+ owner:
760
+ holder === "live"
761
+ ? "live"
762
+ : holder === "dead"
763
+ ? "absent"
764
+ : "ambiguous",
764
765
  };
765
766
  } catch {
766
767
  return { reason: "registry-locked", owner: "unreadable" };
767
768
  }
768
769
  }
769
- private registryRecoveryState() {
770
- const lock = this.files.read(this.registryPath("registry.lock"));
771
- if (!lock) throw new ContractError("conflict");
772
- const value = decodeRegistryLock(lock);
773
- names(this.registryDirectory, registryNames);
774
- const format = this.files.read(this.registryPath("format.json"));
775
- const roots = this.files.read(
776
- this.registryPath("roots.json"),
777
- REGISTRY_BYTES,
778
- );
779
- // A crash immediately after exclusive creation may precede initialization.
780
- const registry = !format && !roots ? undefined : this.registry();
781
- const entries = registry?.value.entries ?? [];
782
- const protectedRoots = new Set(entries.map((row) => hash(row.root)));
783
- const proofs: unknown[] = [];
784
- // Older releases removed a reservation BEFORE the checkout fence. A dead
785
- // short-lock PID cannot make those unreserved, partially released projects
786
- // safe. Verify every unreserved service selection; never repair it here.
787
- const directory = opendirSync(this.files.namespace);
788
- try {
789
- let count = 0;
790
- for (
791
- let entry = directory.readSync();
792
- entry;
793
- entry = directory.readSync()
794
- ) {
795
- if (++count > 1024) throw new ContractError("capacity");
796
- if (
797
- !/^[a-f0-9]{64}$/.test(entry.name) ||
798
- protectedRoots.has(entry.name)
799
- )
800
- continue;
801
- const service = join(this.files.namespace, entry.name, "service-v1");
802
- if (!this.files.directory(service)) continue;
803
- const manifest = this.files.read(join(service, "format.json"));
804
- if (!manifest) refused();
805
- const f = closed(json(manifest), [
806
- "schema",
807
- "root",
808
- "stateHome",
809
- "configIdentity",
810
- ]);
811
- const root = pathValue(f.root);
812
- if (hash(root) !== entry.name) refused();
813
- // Retained stopped metadata remains checkable even when the consumer
814
- // deleted/moved that old working directory. Never resolve/recreate it.
815
- const selected = this.selected(service, root, true);
816
- if (!selected) throw new ContractError("quarantine");
817
- proofs.push([
818
- entry.name,
819
- ...[
820
- selected.manifest,
821
- selected.config,
822
- selected.hostConfig,
823
- selected.registration,
824
- ].map((file) => (file ? [file.identity, file.stamp] : null)),
825
- ]);
826
- }
827
- } finally {
828
- directory.closeSync();
829
- }
830
- proofs.sort((a, b) =>
831
- JSON.stringify(a).localeCompare(JSON.stringify(b), "en"),
832
- );
833
- const stateDigest = hash(
834
- encoded([
835
- lock.identity,
836
- lock.stamp,
837
- format ? [format.identity, format.stamp] : null,
838
- roots ? [roots.identity, roots.stamp] : null,
839
- proofs,
840
- ]),
841
- );
842
- const epoch = hash(encoded([lock.identity, lock.stamp]));
843
- const archive = this.registryPath(join("recovery-v1", epoch));
844
- const attempts: FileSnapshot[] = [];
845
- let previousResolver: RegistryRecoveryInspection["previousResolver"] = null;
846
- if (this.files.directory(archive)) {
847
- // Immutable, exclusive attempts serialize resolvers. If one crashes before
848
- // release, a fresh confirmation may append the next attempt ONLY after its
849
- // PID is absent. No stale secondary lock needs deletion or takeover.
850
- names(
851
- archive,
852
- Array.from({ length: 128 }, (_, n) => `${n}.json`),
853
- );
854
- for (let n = 0; n < 128; n++) {
855
- const attempt = this.files.read(join(archive, `${n}.json`), 32768);
856
- if (!attempt) {
857
- names(
858
- archive,
859
- attempts.map((_, i) => `${i}.json`),
860
- );
861
- break;
862
- }
863
- const o = closed(json(attempt, 32768), [
864
- "schema",
865
- "lock",
866
- "pid",
867
- "host",
868
- "digest",
869
- ]);
870
- literal(o.schema, "cadence-registry-recovery/1");
871
- literal(o.lock, lock.bytes.toString("utf8"));
872
- decodeHash(o.digest);
873
- previousResolver = recoveryOwnerStatus(
874
- integer(o.pid, 1, 2147483647),
875
- text(o.host, 255, true),
876
- );
877
- attempts.push(attempt);
878
- }
879
- }
880
- const inspection: RegistryRecoveryInspection = {
881
- scope: "global-registry",
882
- epoch,
883
- coordinationDigest: hash(
884
- encoded([stateDigest, attempts.map((a) => [a.identity, a.stamp])]),
885
- ),
886
- owner: recoveryOwnerStatus(value.pid, value.host),
887
- process: { pid: value.pid, host: value.host },
888
- reservations: entries.length,
889
- previousResolver,
890
- resolution: "local-interactive-only",
891
- };
892
- return { lock, archive, attempts, stateDigest, inspection };
893
- }
894
- inspectRegistryRecovery(): RegistryRecoveryInspection {
895
- return this.registryRecoveryState().inspection;
896
- }
897
- /** Local native management only. Retire just the proven dead short lock after
898
- * durable evidence; reservations, owner/checkout locks and history stay intact. */
899
- resolveRegistryRecovery(
900
- expected: RegistryRecoveryInspection,
901
- assertAuthority: () => void,
902
- ) {
903
- assertAuthority();
904
- const state = this.registryRecoveryState();
905
- if (encoded(state.inspection) !== encoded(expected))
906
- throw new ContractError("conflict");
907
- if (
908
- expected.owner !== "absent" ||
909
- (expected.previousResolver !== null &&
910
- expected.previousResolver !== "absent")
911
- )
912
- throw new ContractError("quarantine");
913
- if (state.attempts.length >= 128) throw new ContractError("capacity");
914
- assertAuthority();
915
- const receiptPath = join(state.archive, `${state.attempts.length}.json`);
916
- const receipt = this.files.create(
917
- receiptPath,
918
- encoded({
919
- schema: "cadence-registry-recovery/1",
920
- lock: state.lock.bytes.toString("utf8"),
921
- pid: process.pid,
922
- host: hostname(),
923
- digest: expected.coordinationDigest,
924
- }),
925
- 32768,
926
- );
927
- // create fsyncs/closes the original receipt before any release effect.
928
- assertAuthority();
929
- const current = this.registryRecoveryState();
930
- if (
931
- current.stateDigest !== state.stateDigest ||
932
- current.inspection.owner !== "absent" ||
933
- current.attempts.length !== state.attempts.length + 1
934
- )
935
- throw new ContractError("conflict");
936
- for (const [n, attempt] of state.attempts.entries())
937
- this.files.assert(join(state.archive, `${n}.json`), attempt, 32768);
938
- this.files.assert(receiptPath, receipt, 32768);
939
- assertAuthority();
940
- this.files.remove(this.registryPath("registry.lock"), state.lock);
941
- return {
942
- status: "resolved",
943
- scope: "global-registry",
944
- recoveryId: expected.epoch,
945
- notice: "registry-only-project-fences-preserved",
946
- } as const;
947
- }
948
- /** Capture exact private resources BEFORE the append/confirmation awaits. The
949
- * closure is internal local management authority, never a wire capability.
950
- * A durable bridge must be verified by the caller before EVERY release effect. */
951
- prepareRecoveryRelease(
952
- expected: string,
953
- assertAuthority: () => void,
954
- ): (assertDurable: () => void) => void {
955
- assertAuthority();
956
- if (this.recoverySnapshot().digest !== expected)
957
- throw new ContractError("conflict");
958
- const selected = this.selected();
959
- if (
960
- !selected?.value ||
961
- !selected.registration ||
962
- !selected.owner ||
963
- !selected.checkout ||
964
- !selected.capability
965
- )
966
- throw new ContractError("quarantine");
967
- const r = selected.value;
968
- const absent = () => {
969
- assertAuthority();
970
- if (recoveryOwnerStatus(r.pid, r.host) !== "absent")
971
- throw new ContractError("quarantine");
972
- };
973
- absent();
974
- let used = false;
975
- return (assertDurable) => {
976
- if (used) throw new ContractError("consumed-grant");
977
- used = true;
978
- this.withRegistry((view, mutate, assertHeld) => {
979
- let registry = view.snapshot;
980
- let registration = selected.registration;
981
- let capability = selected.capability;
982
- let owner = selected.owner;
983
- let checkout = selected.checkout;
984
- if (!registration || !capability || !owner || !checkout)
985
- throw new ContractError("conflict");
986
- if (recoveryDigest(view, selected) !== expected)
987
- throw new ContractError("conflict");
988
- const assert = () => {
989
- absent();
990
- assertHeld();
991
- this.assertNamespace();
992
- this.files.assert(
993
- this.registryPath("roots.json"),
994
- registry,
995
- REGISTRY_BYTES,
996
- );
997
- for (const [name, snapshot] of [
998
- ["format.json", selected.manifest],
999
- ["config.json", selected.config],
1000
- ["host-config.json", selected.hostConfig],
1001
- ["registration.json", registration],
1002
- ["local-capability.json", capability],
1003
- ["owner.lock", owner],
1004
- ] as const)
1005
- this.files.assert(this.path(name), snapshot);
1006
- this.files.assert(this.store.lockPath, checkout, 8192);
1007
- assertDurable();
1008
- };
1009
- assert();
1010
- const matching = view.value.entries.filter(
1011
- (row) => row.epoch === r.epoch,
1012
- );
1013
- if (
1014
- matching.length !== 1 ||
1015
- encoded(matching[0]) !== encoded(reservation(r))
1016
- )
1017
- throw new ContractError("conflict");
1018
- mutate(); // every subsequent partial failure retains the registry fence
1019
- registration = this.files.replace(
1020
- this.path("registration.json"),
1021
- registration,
1022
- encoded({ ...r, phase: "stopped" }),
1023
- );
1024
- assert();
1025
- registry = this.files.replace(
1026
- this.registryPath("roots.json"),
1027
- registry,
1028
- encoded({
1029
- ...view.value,
1030
- entries: view.value.entries.filter((row) => row.epoch !== r.epoch),
1031
- }),
1032
- REGISTRY_BYTES,
1033
- );
1034
- assert();
1035
- this.files.remove(this.path("local-capability.json"), capability);
1036
- capability = undefined;
1037
- assert();
1038
- this.files.remove(this.path("owner.lock"), owner);
1039
- owner = undefined;
1040
- assert();
1041
- // Only the exact v1 lock tied to THIS registration, never a legacy lock.
1042
- this.files.remove(this.store.lockPath, checkout, 8192);
1043
- checkout = undefined;
1044
- assert();
1045
- });
1046
- };
1047
- }
1048
- /** Private recovery identity only. Does not read/scan task records or logs.
1049
- * W3 independently supplies the affected-history digest; capability bytes and
1050
- * their hashes are deliberately absent from this recovery projection. */
1051
- recoverySnapshot(): { registration: Registration; digest: string } {
1052
- if (this.files.read(this.registryPath("registry.lock")))
1053
- throw new ContractError("quarantine");
1054
- const registry = this.registry();
1055
- const selected = this.selected();
1056
- if (
1057
- !registry ||
1058
- !selected?.value ||
1059
- !selected.registration ||
1060
- !selected.owner ||
1061
- !selected.checkout
1062
- )
1063
- refused();
1064
- const value = selected.value;
1065
- const matching = registry.value.entries.filter(
1066
- (row) => row.epoch === value.epoch,
1067
- );
1068
- if (
1069
- matching.length !== 1 ||
1070
- encoded(matching[0]) !== encoded(reservation(value))
1071
- )
1072
- refused();
1073
- return {
1074
- registration: { ...selected.value },
1075
- digest: recoveryDigest(registry, selected),
1076
- };
1077
- }
1078
770
  }
1079
771
 
1080
772
  /** Held only by the original owner. Raw-byte AND inode/time identities supplement