@amalgm/shell 0.1.125 → 0.1.126
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.
- package/PURPOSE.md +4 -0
- package/dist/content-direct.d.ts +13 -0
- package/dist/content-direct.js +44 -13
- package/dist/content-direct.js.map +1 -1
- package/dist/registry-graph.d.ts +73 -31
- package/dist/registry-graph.js +283 -80
- package/dist/registry-graph.js.map +1 -1
- package/dist/registry-page-cache.d.ts +14 -0
- package/dist/registry-page-cache.js +32 -0
- package/dist/registry-page-cache.js.map +1 -0
- package/dist/user-ground-host.d.ts +28 -7
- package/dist/user-ground-host.js +196 -80
- package/dist/user-ground-host.js.map +1 -1
- package/npm-shrinkwrap.json +6 -6
- package/package.json +2 -2
package/PURPOSE.md
CHANGED
|
@@ -393,6 +393,10 @@ shell only assembles.
|
|
|
393
393
|
they never materialize the complete machine graph merely to answer a
|
|
394
394
|
selected root's yes/no or count question. Cloud publication reads only the
|
|
395
395
|
portable record projection from SQLite, never a second path-and-stat graph.
|
|
396
|
+
A committed cloud registry is likewise held as its small immutable head:
|
|
397
|
+
login reads the core root, Add reads the core root plus its selected
|
|
398
|
+
boundary, and publication carries untouched roots forward by page identity.
|
|
399
|
+
No operation flattens an unrelated cloud root into memory.
|
|
396
400
|
|
|
397
401
|
35. **Container membership is version input, never cargo.** A workspace or
|
|
398
402
|
folder derives its logical version from the UUIDs and names of active
|
package/dist/content-direct.d.ts
CHANGED
|
@@ -16,6 +16,17 @@ interface DirectContentWire {
|
|
|
16
16
|
type: string;
|
|
17
17
|
}, accept: readonly string[]): Promise<Record<string, unknown>>;
|
|
18
18
|
}
|
|
19
|
+
/** What this plane physically did, cumulative since construction. Logical
|
|
20
|
+
* object reads are the caller's count; these are the wire and CPU facts —
|
|
21
|
+
* actual storage GETs, sealed bytes fetched, refs round-trips, decrypt time. */
|
|
22
|
+
export interface DirectContentMetrics {
|
|
23
|
+
readonly rangedGets: number;
|
|
24
|
+
readonly wholeGets: number;
|
|
25
|
+
readonly fetchedBytes: number;
|
|
26
|
+
readonly refsFrames: number;
|
|
27
|
+
readonly refsMs: number;
|
|
28
|
+
readonly decryptMs: number;
|
|
29
|
+
}
|
|
19
30
|
export declare class DirectContentPlane {
|
|
20
31
|
/** Key material is stable for a resource's lifetime, so one handoff per
|
|
21
32
|
* process is enough; it lives only in memory, never at rest. */
|
|
@@ -23,7 +34,9 @@ export declare class DirectContentPlane {
|
|
|
23
34
|
private readonly brokers;
|
|
24
35
|
private readonly spans;
|
|
25
36
|
private readonly wire;
|
|
37
|
+
private readonly counters;
|
|
26
38
|
constructor(wire: DirectContentWire);
|
|
39
|
+
metrics(): DirectContentMetrics;
|
|
27
40
|
/** Fetch one sealed storage object and open it. Every attempt asks for a
|
|
28
41
|
* fresh ref — URL expiry is the gateway's revocation lever, so URLs are
|
|
29
42
|
* used immediately and never reused. */
|
package/dist/content-direct.js
CHANGED
|
@@ -42,9 +42,27 @@ export class DirectContentPlane {
|
|
|
42
42
|
brokers = new Map();
|
|
43
43
|
spans;
|
|
44
44
|
wire;
|
|
45
|
+
counters = {
|
|
46
|
+
rangedGets: 0, wholeGets: 0, fetchedBytes: 0, refsFrames: 0, refsMs: 0, decryptMs: 0,
|
|
47
|
+
};
|
|
45
48
|
constructor(wire) {
|
|
46
49
|
this.wire = wire;
|
|
47
|
-
this.spans = createSpanFetcher({
|
|
50
|
+
this.spans = createSpanFetcher({
|
|
51
|
+
fetchSpan: async (url, span) => {
|
|
52
|
+
// Count physical attempts, including failures that retry. Successful
|
|
53
|
+
// bytes are counted separately once storage answers.
|
|
54
|
+
if (span)
|
|
55
|
+
this.counters.rangedGets += 1;
|
|
56
|
+
else
|
|
57
|
+
this.counters.wholeGets += 1;
|
|
58
|
+
const bytes = await fetchStorageSpan(url, span);
|
|
59
|
+
this.counters.fetchedBytes += bytes.byteLength;
|
|
60
|
+
return bytes;
|
|
61
|
+
},
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
metrics() {
|
|
65
|
+
return { ...this.counters };
|
|
48
66
|
}
|
|
49
67
|
/** Fetch one sealed storage object and open it. Every attempt asks for a
|
|
50
68
|
* fresh ref — URL expiry is the gateway's revocation lever, so URLs are
|
|
@@ -72,12 +90,18 @@ export class DirectContentPlane {
|
|
|
72
90
|
}
|
|
73
91
|
throw error;
|
|
74
92
|
}
|
|
75
|
-
const
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
93
|
+
const decryptStarted = performance.now();
|
|
94
|
+
try {
|
|
95
|
+
const opened = await openProtectedEnvelopeBytes(key, sealed, {
|
|
96
|
+
resourceId,
|
|
97
|
+
contract,
|
|
98
|
+
purpose: "entity-content",
|
|
99
|
+
});
|
|
100
|
+
return Buffer.from(opened.buffer, opened.byteOffset, opened.byteLength);
|
|
101
|
+
}
|
|
102
|
+
finally {
|
|
103
|
+
this.counters.decryptMs += performance.now() - decryptStarted;
|
|
104
|
+
}
|
|
81
105
|
}
|
|
82
106
|
contentKey(resourceId) {
|
|
83
107
|
let pending = this.keys.get(resourceId);
|
|
@@ -109,12 +133,19 @@ export class DirectContentPlane {
|
|
|
109
133
|
if (!broker) {
|
|
110
134
|
broker = createRefsBroker({
|
|
111
135
|
requestRefs: async (objects) => {
|
|
112
|
-
const
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
136
|
+
const refsStarted = performance.now();
|
|
137
|
+
this.counters.refsFrames += 1;
|
|
138
|
+
try {
|
|
139
|
+
const frame = await this.wire.request({
|
|
140
|
+
type: "private.entity-content.refs",
|
|
141
|
+
resource_id: resourceId,
|
|
142
|
+
objects: objects.map((object) => ({ kind: object.kind, sha256: object.sha256 })),
|
|
143
|
+
}, ["private.entity-content.refs-result"]);
|
|
144
|
+
return decodeRefs(frame);
|
|
145
|
+
}
|
|
146
|
+
finally {
|
|
147
|
+
this.counters.refsMs += performance.now() - refsStarted;
|
|
148
|
+
}
|
|
118
149
|
},
|
|
119
150
|
});
|
|
120
151
|
this.brokers.set(resourceId, broker);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"content-direct.js","sourceRoot":"","sources":["../src/content-direct.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,0BAA0B,GAM3B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"content-direct.js","sourceRoot":"","sources":["../src/content-direct.ts"],"names":[],"mappings":"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"}
|
package/dist/registry-graph.d.ts
CHANGED
|
@@ -2,17 +2,29 @@
|
|
|
2
2
|
* The registry graph as this machine holds it.
|
|
3
3
|
*
|
|
4
4
|
* The authority stores the graph as a small head naming each root's immutable
|
|
5
|
-
* pages,
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
5
|
+
* pages, and this machine holds exactly that: the head, plus the records of
|
|
6
|
+
* only the roots the current operation acts on. Nothing ever materializes the
|
|
7
|
+
* whole account — an Add reads its boundary root and the core root, a Register
|
|
8
|
+
* reads the roots it rebuilds, and every other root stays as page identities.
|
|
9
|
+
*
|
|
10
|
+
* Two page laws make root-scoped reading exact and cheap:
|
|
11
|
+
* - A root's pages are one contiguous uuid-sorted slice, so any single uuid
|
|
12
|
+
* is found (or proven absent) by binary-searching pages — log(pages) page
|
|
13
|
+
* reads, each proven against its declared identity and dropped after use.
|
|
14
|
+
* - Set-membership questions sweep pages one at a time, so their transient
|
|
15
|
+
* memory is O(page), never O(graph).
|
|
9
16
|
*
|
|
10
17
|
* A resource whose authority snapshot is still records-shaped (a login's
|
|
11
18
|
* initial publication, before any head has committed) is held with a null
|
|
12
|
-
* head
|
|
13
|
-
*
|
|
19
|
+
* head and every record in memory — such graphs are one machine's first
|
|
20
|
+
* publication and small by construction. Its first head commit must page
|
|
21
|
+
* every root at once, which is exactly what the authority demands of a
|
|
22
|
+
* commit over a records base.
|
|
14
23
|
*/
|
|
15
24
|
import { type CloudEntityRecord, type CloudSnapshot, type CloudGraphHead, type CloudGraphHeadReplacement, type GraphPage, type GraphPageRef, type Sha256Hex } from "@amalgm/live";
|
|
25
|
+
/** Read one immutable page's bytes by identity. The reader owns caching and
|
|
26
|
+
* transport; the graph owns every proof over what comes back. */
|
|
27
|
+
export type GraphPageReader = (ref: GraphPageRef) => Promise<Uint8Array>;
|
|
16
28
|
/** One publication's outcome: the graph it produces, the operation that
|
|
17
29
|
* commits it, the pages that must be sealed first, and the checksum the
|
|
18
30
|
* authority will hold once it lands. */
|
|
@@ -26,36 +38,66 @@ export declare class RegistryGraph {
|
|
|
26
38
|
/** The committed head, or null while the authority still holds a
|
|
27
39
|
* records-shaped snapshot. */
|
|
28
40
|
readonly head: CloudGraphHead | null;
|
|
29
|
-
private readonly
|
|
30
|
-
private
|
|
31
|
-
private
|
|
32
|
-
constructor(
|
|
33
|
-
/** Hold a records-shaped snapshot
|
|
34
|
-
*
|
|
35
|
-
static fromRecords(records: readonly CloudEntityRecord[]): RegistryGraph;
|
|
41
|
+
private readonly roots;
|
|
42
|
+
private readonly readPage;
|
|
43
|
+
private readonly sha256Hex;
|
|
44
|
+
private constructor();
|
|
45
|
+
/** Hold a records-shaped snapshot fully materialized: it is a first
|
|
46
|
+
* publication's own graph and carries no page identities to defer to. */
|
|
47
|
+
static fromRecords(records: readonly CloudEntityRecord[], sha256Hex: Sha256Hex): RegistryGraph;
|
|
48
|
+
/** Hold a committed head lazily: every root starts as page identities and
|
|
49
|
+
* materializes only when an operation reads it. */
|
|
50
|
+
static fromHead(head: CloudGraphHead, readPage: GraphPageReader, sha256Hex: Sha256Hex): RegistryGraph;
|
|
36
51
|
rootIds(): readonly string[];
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
52
|
+
/** The records of one root as this machine has already materialized them,
|
|
53
|
+
* or null when that root is still page identities. */
|
|
54
|
+
loadedRecords(rootId: string): readonly CloudEntityRecord[] | null;
|
|
55
|
+
/** Materialize one root: every page proven and parsed in order with a
|
|
56
|
+
* bounded prefetch, bytes dropped as they are consumed, then the root's
|
|
57
|
+
* complete subtree and canonical-pagination proof. An absent root answers
|
|
58
|
+
* empty rather than faulting — reading a root that is not there is how
|
|
59
|
+
* callers learn it is not there. */
|
|
60
|
+
recordsFor(rootId: string): Promise<readonly CloudEntityRecord[]>;
|
|
61
|
+
/** One root's own record — the discovery unit. Found by binary search over
|
|
62
|
+
* the root's uuid-sorted pages without materializing the root; each probed
|
|
63
|
+
* page is proven against its identity and dropped. */
|
|
64
|
+
rootRecord(rootId: string): Promise<CloudEntityRecord>;
|
|
65
|
+
/** Every root's own record, for discovery over the whole account — which
|
|
66
|
+
* root is the core, which roots are workspaces — at log(pages) page reads
|
|
67
|
+
* per root instead of materializing anything. */
|
|
68
|
+
rootRecords(): Promise<readonly CloudEntityRecord[]>;
|
|
69
|
+
/** Which root holds this uuid, or null when the graph does not. A uuid that
|
|
70
|
+
* names a root is answered directly; anything else binary-searches each
|
|
71
|
+
* root's pages, materialized roots answered from memory. */
|
|
72
|
+
locate(uuid: string): Promise<string | null>;
|
|
73
|
+
/** Which root holds each of these uuids. Materialized roots answer from
|
|
74
|
+
* memory; the rest are swept page-at-a-time with transient parses, so one
|
|
75
|
+
* miss-heavy question — a publication merge asking about thousands of
|
|
76
|
+
* fresh uuids — costs one bounded pass, not one probe per uuid. */
|
|
77
|
+
membership(uuids: ReadonlySet<string>): Promise<ReadonlyMap<string, string>>;
|
|
48
78
|
/** The checksum the authority holds for this graph right now. */
|
|
49
|
-
checksum(
|
|
79
|
+
checksum(): string;
|
|
80
|
+
/** The records shape of a headless graph — a first publication's own small
|
|
81
|
+
* snapshot. A committed head never flattens: readers are root-scoped. */
|
|
82
|
+
recordsShapedSnapshot(): CloudSnapshot;
|
|
50
83
|
/** Publish a new graph in which `rebuilt` roots carry the given records and
|
|
51
|
-
* every other root carries its committed pages
|
|
84
|
+
* every other root carries its committed pages — and any records this
|
|
85
|
+
* machine already materialized for them — forward. A root mapped to an
|
|
52
86
|
* empty record list is dropped from the graph. */
|
|
53
|
-
rebuild(rebuilt: ReadonlyMap<string, readonly CloudEntityRecord[]
|
|
87
|
+
rebuild(rebuilt: ReadonlyMap<string, readonly CloudEntityRecord[]>): RegistryGraphRebuild;
|
|
88
|
+
/** Prove, parse, and visit pages in order, fetching a bounded window ahead
|
|
89
|
+
* so the network pipeline stays full while transient memory stays at a few
|
|
90
|
+
* page budgets. The visitor may answer true to stop the scan early. */
|
|
91
|
+
private scanPages;
|
|
92
|
+
/** Binary-search one root's uuid-sorted pages for a single uuid. Each
|
|
93
|
+
* probed page is proven and dropped; the hit is normalized through the
|
|
94
|
+
* canonical record law before anyone reads it. */
|
|
95
|
+
private findInPages;
|
|
54
96
|
}
|
|
55
97
|
/** Every page identity the head names — the set a publication may skip
|
|
56
98
|
* uploading because the authority already holds it under this exact graph. */
|
|
57
99
|
export declare function graphPageIdentities(head: CloudGraphHead | null): ReadonlySet<string>;
|
|
58
|
-
/**
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
export declare function registryGraphFromSnapshot(bytes: Uint8Array,
|
|
100
|
+
/** Hold the authority's stored snapshot bytes as this machine's graph. A head
|
|
101
|
+
* is held lazily — no page is read here — and a records-shaped snapshot is
|
|
102
|
+
* grouped in place. */
|
|
103
|
+
export declare function registryGraphFromSnapshot(bytes: Uint8Array, readPage: GraphPageReader, sha256Hex: Sha256Hex): RegistryGraph;
|