@starci/seed 0.0.0-stage → 0.2.0

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.
@@ -0,0 +1,219 @@
1
+ import { exportOnce, memorySpool, restoreFrom, writeEverywhere } from "../copies.js";
2
+ import { DataRefusal } from "../driver.js";
3
+ import { blobEntry, byteOrder, entryIntact, recordEntry, recordValue } from "../manifest.js";
4
+ function check(condition, message) {
5
+ if (!condition)
6
+ throw new Error(`contract broken: ${message}`);
7
+ }
8
+ async function collect(items) {
9
+ const out = [];
10
+ for await (const item of items)
11
+ out.push(item);
12
+ return out;
13
+ }
14
+ async function* from(items) {
15
+ await Promise.resolve();
16
+ yield* items;
17
+ }
18
+ const header = { format: "contract-seed-backup@1", purpose: "seed-backup", takenAt: "2026-01-01T00:00:00.000Z", source: { project: "contract", environment: "test" } };
19
+ const sameBytes = (left, right) => left.sha256 === right.sha256 && left.key === right.key && left.set === right.set;
20
+ /**
21
+ * The promises every store adapter keeps. `make` builds a fresh store holding at least one entry; `empty` a fresh store of
22
+ * the same kind holding nothing, the target of an import. A real adapter runs this suite against its fakes. A store that
23
+ * holds only typed rows (a database) says in `change` how one of its entries becomes another valid one.
24
+ */
25
+ export function storeContract(make, empty, options = {}) {
26
+ return [
27
+ {
28
+ name: "describes its sets, each with a schema and a form, and says what it cannot do",
29
+ run: async () => {
30
+ const description = await (await make()).describe();
31
+ check(description.sets.length > 0, "a store with content describes at least one set");
32
+ check(description.sets.every((set) => set.schema !== ""), "every set has a schema");
33
+ check(Array.isArray(description.cannot), "cannot is a list, even when empty");
34
+ },
35
+ },
36
+ {
37
+ name: "exports in (set, key) byte order, every entry intact, each key once",
38
+ run: async () => {
39
+ const entries = await collect((await make()).export({}));
40
+ check(entries.length > 0, "the export holds entries");
41
+ check(entries.every(entryIntact), "every sha256 matches its body");
42
+ entries.reduce((before, after) => {
43
+ check((byteOrder(before.set, after.set) || byteOrder(before.key, after.key)) < 0, `${after.set}/${after.key} is out of order or repeated`);
44
+ return after;
45
+ });
46
+ },
47
+ },
48
+ {
49
+ name: "exports the same content twice as the same bytes",
50
+ run: async () => {
51
+ const store = await make();
52
+ const first = await collect(store.export({}));
53
+ const second = await collect(store.export({}));
54
+ check(first.length === second.length && first.every((entry, at) => second[at] !== undefined && sameBytes(entry, second[at])), "two exports differ");
55
+ },
56
+ },
57
+ {
58
+ name: "exports only the selected sets",
59
+ run: async () => {
60
+ const store = await make();
61
+ const [first] = (await store.describe()).sets;
62
+ const entries = await collect(store.export({ sets: [first?.set ?? ""] }));
63
+ check(entries.every((entry) => entry.set === first?.set), "an entry of an unselected set was exported");
64
+ },
65
+ },
66
+ {
67
+ name: "imports idempotently by natural key: the second import changes nothing",
68
+ run: async () => {
69
+ const entries = await collect((await make()).export({}));
70
+ const target = await empty();
71
+ const first = await target.import(from(entries), { dryRun: false, mode: "merge" });
72
+ check(first.outcome === "applied", `the first import answered ${first.outcome}`);
73
+ const second = await target.import(from(entries), { dryRun: false, mode: "merge" });
74
+ check(second.outcome === "unchanged", `the second import answered ${second.outcome}`);
75
+ },
76
+ },
77
+ {
78
+ name: "a re-import keeps every identity: the same entries keep the same ids (relations stay valid)",
79
+ run: async () => {
80
+ const entries = await collect((await make()).export({}));
81
+ const target = await empty();
82
+ await target.import(from(entries), { dryRun: false, mode: "merge" });
83
+ const before = await Promise.all(entries.map((entry) => target.identityOf(entry.set, entry.key)));
84
+ check(before.every((id) => id !== null), "an imported key has no identity");
85
+ await target.import(from(entries), { dryRun: false, mode: "merge" });
86
+ const after = await Promise.all(entries.map((entry) => target.identityOf(entry.set, entry.key)));
87
+ check(after.every((id, at) => id === before[at]), "a re-import changed an identity");
88
+ },
89
+ },
90
+ {
91
+ name: "a changed entry is updated in place: same identity, new content",
92
+ run: async () => {
93
+ const entries = await collect((await make()).export({}));
94
+ const target = await empty();
95
+ await target.import(from(entries), { dryRun: false, mode: "merge" });
96
+ const first = entries.find((entry) => entry.form === "record") ?? entries[0];
97
+ if (first === undefined)
98
+ throw new Error("contract broken: no entry to change");
99
+ const id = await target.identityOf(first.set, first.key);
100
+ const changed = options.change !== undefined
101
+ ? options.change(first)
102
+ : first.form === "record"
103
+ ? recordEntry(first.set, first.key, { ...recordValue(first), contractChanged: true })
104
+ : blobEntry(first.set, first.key, new Uint8Array([...first.body, 1]), first.media);
105
+ const report = await target.import(from([changed]), { dryRun: false, mode: "merge" });
106
+ check(report.sets.some((set) => set.updated === 1), "the changed entry was not counted as an update");
107
+ check((await target.identityOf(first.set, first.key)) === id, "the update re-created the row");
108
+ const back = await collect(target.export({ sets: [first.set] }));
109
+ check(back.some((entry) => entry.key === first.key && entry.sha256 === changed.sha256), "the new content was not written");
110
+ },
111
+ },
112
+ {
113
+ name: "a merge leaves alone every key the entries do not name",
114
+ run: async () => {
115
+ const entries = await collect((await make()).export({}));
116
+ const target = await empty();
117
+ await target.import(from(entries), { dryRun: false, mode: "merge" });
118
+ const sets = new Map();
119
+ for (const entry of entries)
120
+ sets.set(entry.set, [...(sets.get(entry.set) ?? []), entry]);
121
+ const several = [...sets.values()].find((items) => items.length > 1) ?? entries;
122
+ const report = await target.import(from(several.slice(0, 1)), { dryRun: false, mode: "merge" });
123
+ check(report.sets.every((set) => set.removed === 0), "a merge removed a key");
124
+ const back = await collect(target.export({}));
125
+ check(back.length === entries.length, "a key absent from the import disappeared");
126
+ },
127
+ },
128
+ {
129
+ name: "a dry-run import writes nothing",
130
+ run: async () => {
131
+ const entries = await collect((await make()).export({}));
132
+ const target = await empty();
133
+ await target.import(from(entries), { dryRun: true, mode: "merge" });
134
+ const after = await collect(target.export({}));
135
+ check(after.length === 0, "a dry run wrote entries");
136
+ },
137
+ },
138
+ {
139
+ name: "export then import into an empty store round-trips every entry",
140
+ run: async () => {
141
+ const entries = await collect((await make()).export({}));
142
+ const target = await empty();
143
+ await target.import(from(entries), { dryRun: false, mode: "merge" });
144
+ const back = await collect(target.export({}));
145
+ check(back.length === entries.length && back.every((entry, at) => entries[at] !== undefined && sameBytes(entry, entries[at])), "the round trip changed the content");
146
+ },
147
+ },
148
+ ];
149
+ }
150
+ /**
151
+ * The promises every driver adapter keeps. `make` builds a fresh driver; `store` a store with content to export; `open`
152
+ * the identity a sealed copy is read with (a throwaway test key in a driver's own specs, never a real one).
153
+ */
154
+ export function driverContract(make, store, context, open = { identity: { kind: "age-identity", env: {} } }) {
155
+ const exported = async () => exportOnce([await store()], {}, memorySpool(), header);
156
+ return [
157
+ {
158
+ name: "plans a holding of the export, naming every omitted set",
159
+ run: async () => {
160
+ const source = await exported();
161
+ const holding = (await make()).plan(source.manifest);
162
+ check(holding.exportDigest === source.manifest.exportDigest, "the holding names another export");
163
+ check((holding.holds === "all") === (holding.omitted.length === 0), "holds and omitted disagree");
164
+ },
165
+ },
166
+ {
167
+ name: "writes, lists, reads back the same entries and verifies healthy",
168
+ run: async () => {
169
+ const driver = await make();
170
+ const source = await exported();
171
+ const receipt = await driver.write(source, context);
172
+ const [ref] = await driver.list();
173
+ if (ref === undefined)
174
+ throw new Error("contract broken: no copy listed after a write");
175
+ check(ref.exportDigest === source.manifest.exportDigest, "the newest copy is not the export written");
176
+ check(receipt.ref.locator === ref.locator, "the receipt names another copy");
177
+ const back = await collect((await driver.read(ref, open)).entries());
178
+ const sent = await collect(source.entries());
179
+ check(back.length === sent.length && back.every((item, at) => sameBytes(item.entry, sent[at].entry)), "the copy reads back other entries");
180
+ const verdict = await driver.verify(ref, open);
181
+ check(verdict.healthy, `verify: ${verdict.checks.filter((item) => !item.ok).map((item) => item.detail).join("; ")}`);
182
+ },
183
+ },
184
+ {
185
+ name: "writing an export it already holds changes nothing",
186
+ run: async () => {
187
+ const driver = await make();
188
+ const source = await exported();
189
+ await driver.write(source, context);
190
+ const again = await driver.write(source, context);
191
+ check(again.changed === 0, `the second write changed ${String(again.changed)} files`);
192
+ },
193
+ },
194
+ {
195
+ name: "a failing driver is one failed leg; the others still hold the export",
196
+ run: async () => {
197
+ const driver = await make();
198
+ const broken = { ...driver, id: "broken", write: () => Promise.reject(new DataRefusal("DATA_DRIVER_UNAVAILABLE", "transient")) };
199
+ const run = await writeEverywhere(await exported(), [driver, broken], context);
200
+ check(run.outcome === "partial", `the run answered ${run.outcome}`);
201
+ check(run.legs[1]?.failure?.code === "DATA_DRIVER_UNAVAILABLE", "the failed leg lost its code");
202
+ },
203
+ },
204
+ {
205
+ name: "a copy restores into an empty store",
206
+ run: async () => {
207
+ const driver = await make();
208
+ const source = await exported();
209
+ await driver.write(source, context);
210
+ const [ref] = await driver.list();
211
+ if (ref === undefined)
212
+ throw new Error("contract broken: no copy listed");
213
+ const target = await store();
214
+ const reports = await restoreFrom(await driver.read(ref, open), [target], { dryRun: false, mode: "merge" });
215
+ check(reports.every((report) => report.outcome !== "partial"), "the restore was refused in part");
216
+ },
217
+ },
218
+ ];
219
+ }
@@ -0,0 +1,5 @@
1
+ export { memoryDriver, memoryStore } from "./memory.js";
2
+ export type { MemoryDriver, MemoryDriverInit, MemorySets, MemoryStore, MemoryStoreInit } from "./memory.js";
3
+ export { driverContract, storeContract } from "./contract.js";
4
+ export type { ContractCase, StoreContractOptions } from "./contract.js";
5
+ export { memorySpool } from "../copies.js";
@@ -0,0 +1,3 @@
1
+ export { memoryDriver, memoryStore } from "./memory.js";
2
+ export { driverContract, storeContract } from "./contract.js";
3
+ export { memorySpool } from "../copies.js";
@@ -0,0 +1,53 @@
1
+ import type { DriverAdapter, DriverLimits } from "../driver.js";
2
+ import type { JsonValue } from "../manifest.js";
3
+ import type { Inability, StoreAdapter } from "../store.js";
4
+ import type { DataRefusalCode } from "../driver.js";
5
+ import type { DriverKind, StoreKind, StoreLevel } from "../words.js";
6
+ /** The content of a memory store: set -> key -> a record value or blob bytes. */
7
+ export type MemorySets = Record<string, Record<string, JsonValue | Uint8Array>>;
8
+ /** What a memory store starts with. */
9
+ export interface MemoryStoreInit {
10
+ /** The store id. */
11
+ readonly id: string;
12
+ /** The kind; `database` by default. */
13
+ readonly kind?: StoreKind;
14
+ /** The level; `logical` by default. */
15
+ readonly level?: StoreLevel;
16
+ /** The content. */
17
+ readonly sets?: MemorySets;
18
+ /** The schema format of its record sets, e.g. `shop-seed-standard@1`. */
19
+ readonly format?: string;
20
+ /** What it says it cannot do. */
21
+ readonly cannot?: readonly Inability[];
22
+ /** Keys whose import the door refuses, with the refusal code. */
23
+ readonly refuse?: Readonly<Record<string, string>>;
24
+ }
25
+ /** A memory store, with a view of what it holds now. */
26
+ export interface MemoryStore extends StoreAdapter {
27
+ /** A copy of the content, for assertions. */
28
+ snapshot(): MemorySets;
29
+ }
30
+ /** A store over plain maps: deterministic export in (set, key) byte order; merge and mirror imports with exact counts. */
31
+ export declare function memoryStore(init: MemoryStoreInit): MemoryStore;
32
+ /** What a memory driver starts with. */
33
+ export interface MemoryDriverInit {
34
+ /** The driver id. */
35
+ readonly id: string;
36
+ /** The kind; `git` by default. */
37
+ readonly kind?: DriverKind;
38
+ /** Limits; a git driver's by default (records and blobs, the 500 MiB whole-copy cap measured on entry bytes). */
39
+ readonly limits?: Partial<DriverLimits>;
40
+ /** Fails one operation with this code, to test partial runs and chooseCopy. */
41
+ readonly fail?: {
42
+ readonly on: "write" | "read" | "verify";
43
+ readonly code: DataRefusalCode;
44
+ readonly retry?: "configuration" | "transient";
45
+ };
46
+ }
47
+ /** A memory driver, with a hook to corrupt a kept copy. */
48
+ export interface MemoryDriver extends DriverAdapter {
49
+ /** Changes one entry of the newest copy without changing its manifest, as a corrupted shard would. */
50
+ corrupt(set: string, key: string): void;
51
+ }
52
+ /** A driver over a list of kept copies, newest first, with real limits applied. */
53
+ export declare function memoryDriver(init: MemoryDriverInit): MemoryDriver;
Binary file
@@ -0,0 +1,33 @@
1
+ /**
2
+ * The closed vocabulary of the data standard (PROJECT-STACKS-14). A new store kind or driver is a harness change: this
3
+ * file, the rule that lists it (R426, R427) and the stack manifest's parser move together, never an app's choice.
4
+ */
5
+ /** What must be kept: the relational database, or the object store (its buckets and their binaries). */
6
+ export type StoreKind = "database" | "storage";
7
+ /** Where a copy is kept: a sealed git repository now, an S3 bucket when the project outgrows git. */
8
+ export type DriverKind = "git" | "s3";
9
+ /**
10
+ * The two kinds of seed, which differ only in who writes them and when they are read:
11
+ * `seed-standard`: curated by people, pinned by commit, loaded by default when an environment or workspace is created;
12
+ * `seed-backup`: written only by the scheduled backup job, read back only by an explicit `sync`, never loaded by default.
13
+ */
14
+ export type DataPurpose = "seed-standard" | "seed-backup";
15
+ /**
16
+ * `logical`: records by natural key, read and written through the app's own doors (portable, idempotent, partial).
17
+ * `physical`: the engine's own dump; restored whole only, and only from a `seed-backup`.
18
+ */
19
+ export type StoreLevel = "logical" | "physical";
20
+ /** `record`: one canonical JSON object. `blob`: opaque bytes (a stored file, a part of a dump). */
21
+ export type EntryForm = "record" | "blob";
22
+ /** The store kinds, in the order the manifest lists them. */
23
+ export declare const STORE_KINDS: readonly StoreKind[];
24
+ /** The drivers, in the order the manifest lists them. */
25
+ export declare const DRIVER_KINDS: readonly DriverKind[];
26
+ /** The purposes. */
27
+ export declare const DATA_PURPOSES: readonly DataPurpose[];
28
+ /** The whole snapshot one git copy may hold (its data files in the working tree, history not counted): 500 MiB. Past it the copy needs s3. */
29
+ export declare const GIT_CAP_BYTES = 524288000;
30
+ /** The size at which a git copy warns that it nears its cap: 80% of it, 400 MiB. */
31
+ export declare const GIT_WARN_BYTES = 419430400;
32
+ /** The largest shard or blob chunk file the git driver writes: 4 MiB, far under GitHub's 50 MiB push warning and 100 MiB per-file block. */
33
+ export declare const GIT_SHARD_BYTES = 4194304;
package/dist/words.js ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * The closed vocabulary of the data standard (PROJECT-STACKS-14). A new store kind or driver is a harness change: this
3
+ * file, the rule that lists it (R426, R427) and the stack manifest's parser move together, never an app's choice.
4
+ */
5
+ /** The store kinds, in the order the manifest lists them. */
6
+ export const STORE_KINDS = Object.freeze(["database", "storage"]);
7
+ /** The drivers, in the order the manifest lists them. */
8
+ export const DRIVER_KINDS = Object.freeze(["git", "s3"]);
9
+ /** The purposes. */
10
+ export const DATA_PURPOSES = Object.freeze(["seed-standard", "seed-backup"]);
11
+ /** The whole snapshot one git copy may hold (its data files in the working tree, history not counted): 500 MiB. Past it the copy needs s3. */
12
+ export const GIT_CAP_BYTES = 524_288_000;
13
+ /** The size at which a git copy warns that it nears its cap: 80% of it, 400 MiB. */
14
+ export const GIT_WARN_BYTES = 419_430_400;
15
+ /** The largest shard or blob chunk file the git driver writes: 4 MiB, far under GitHub's 50 MiB push warning and 100 MiB per-file block. */
16
+ export const GIT_SHARD_BYTES = 4_194_304;
package/package.json CHANGED
@@ -1,6 +1,87 @@
1
1
  {
2
2
  "name": "@starci/seed",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "The data standard of a StarCi project in one package: the two kinds of seed, the standard seed (loaded once by the bring-up) and the backup seed (written by the scheduled job, brought back by a sync). The ports (store and driver adapters, one export to several copies, the copy contract and the line protocol), in-memory references with the store and driver contract suites under ./testing, a git driver (sealed by purpose with sops and age) under ./git, and the postgres store (the whole relational database as deterministic per-table rows) under ./postgres.",
5
+ "keywords": [
6
+ "seed",
7
+ "backup",
8
+ "data",
9
+ "sync",
10
+ "git",
11
+ "sops",
12
+ "age"
13
+ ],
14
+ "license": "MIT",
15
+ "author": "starci183",
16
+ "homepage": "https://github.com/starci183/starci-harness/tree/main/packages/seed#readme",
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/starci183/starci-harness.git",
20
+ "directory": "packages/seed"
21
+ },
22
+ "bugs": {
23
+ "url": "https://github.com/starci183/starci-harness/issues"
24
+ },
25
+ "private": false,
26
+ "type": "module",
27
+ "main": "./dist/index.js",
28
+ "types": "./dist/index.d.ts",
29
+ "exports": {
30
+ ".": {
31
+ "types": "./dist/index.d.ts",
32
+ "default": "./dist/index.js"
33
+ },
34
+ "./testing": {
35
+ "types": "./dist/testing/index.d.ts",
36
+ "default": "./dist/testing/index.js"
37
+ },
38
+ "./git": {
39
+ "types": "./dist/git/index.d.ts",
40
+ "default": "./dist/git/index.js"
41
+ },
42
+ "./postgres": {
43
+ "types": "./dist/postgres/index.d.ts",
44
+ "default": "./dist/postgres/index.js"
45
+ },
46
+ "./package.json": "./package.json"
47
+ },
48
+ "files": [
49
+ "dist",
50
+ "!dist/**/*.spec.*",
51
+ "LICENSE",
52
+ "README.md",
53
+ "CHANGELOG.md"
54
+ ],
55
+ "sideEffects": false,
56
+ "engines": {
57
+ "node": ">=20"
58
+ },
59
+ "scripts": {
60
+ "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.build.json && node -e \"const fs = require('node:fs'); for (const f of fs.readdirSync('dist', {recursive: true}).filter((n) => n.endsWith('.d.ts'))) fs.writeFileSync('dist/' + f, fs.readFileSync('dist/' + f, 'utf8').replace(/((?:from |import\\()['\\x22]\\.\\.?\\/[^'\\x22]+)\\.ts(['\\x22])/g, (all, head, quote) => head + '.js' + quote))\"",
61
+ "typecheck": "tsc -p tsconfig.json --noEmit",
62
+ "lint": "eslint .",
63
+ "test": "npm run typecheck && npm run lint && node --test --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-exclude=\"src/**/*.spec.ts\" --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 \"src/**/*.spec.ts\"",
64
+ "prepack": "npm run build",
65
+ "prepublishOnly": "npm test && npm run build"
66
+ },
67
+ "dependencies": {
68
+ "@starci/common": "1.0.1"
69
+ },
70
+ "devDependencies": {
71
+ "@eslint/js": "10.0.1",
72
+ "@starci/common": "file:../common",
73
+ "@types/node": "22.20.4",
74
+ "@types/pg": "8.23.1",
75
+ "eslint": "10.13.0",
76
+ "jiti": "2.7.0",
77
+ "pg": "8.23.1",
78
+ "typescript": "5.9.3",
79
+ "typescript-eslint": "8.72.0"
80
+ },
81
+ "publishConfig": {
82
+ "access": "public",
83
+ "provenance": true
84
+ },
85
+ "gitHead": "018abe9f5bb449009b53897924abecaa64280aef",
86
+ "starciSource": "af5a83287e764db366a30cf4ccde45e7b9dfb9ddc20e70cde410ddcc4a96a180"
87
+ }