@eidos.space/eidos-file 0.1.0 → 1.0.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.
Files changed (43) hide show
  1. package/DEVELOPER_PLATFORM.md +49 -53
  2. package/README.md +66 -99
  3. package/dist/adapter-contract-B3p-48Yb.d.mts +1149 -0
  4. package/dist/adapter-contract-B3p-48Yb.d.mts.map +1 -0
  5. package/dist/better-sqlite3.d.mts +64 -3
  6. package/dist/better-sqlite3.d.mts.map +1 -1
  7. package/dist/better-sqlite3.mjs +387 -14
  8. package/dist/better-sqlite3.mjs.map +1 -1
  9. package/dist/browser.d.mts +4 -3
  10. package/dist/browser.d.mts.map +1 -1
  11. package/dist/browser.mjs +30 -11
  12. package/dist/browser.mjs.map +1 -1
  13. package/dist/csv-WEud-i_H.mjs +376 -0
  14. package/dist/csv-WEud-i_H.mjs.map +1 -0
  15. package/dist/csv.d.mts +1 -1
  16. package/dist/csv.d.mts.map +1 -1
  17. package/dist/csv.mjs +1 -248
  18. package/dist/index.d.mts +312 -18
  19. package/dist/index.d.mts.map +1 -1
  20. package/dist/index.mjs +3237 -4
  21. package/dist/index.mjs.map +1 -0
  22. package/dist/runtime-CMdfE7Gx.mjs +5476 -0
  23. package/dist/runtime-CMdfE7Gx.mjs.map +1 -0
  24. package/dist/runtime-DCo5E0Kr.d.mts +668 -0
  25. package/dist/runtime-DCo5E0Kr.d.mts.map +1 -0
  26. package/dist/select-options-DihMTuoa.mjs +518 -0
  27. package/dist/select-options-DihMTuoa.mjs.map +1 -0
  28. package/dist/sqlite-wasm-B86yaLG6.mjs +2000 -0
  29. package/dist/sqlite-wasm-B86yaLG6.mjs.map +1 -0
  30. package/dist/temporal-CVzLU63l.d.mts +517 -0
  31. package/dist/temporal-CVzLU63l.d.mts.map +1 -0
  32. package/package.json +2 -3
  33. package/dist/csv.mjs.map +0 -1
  34. package/dist/host-CqP1MeMK.d.mts +0 -213
  35. package/dist/host-CqP1MeMK.d.mts.map +0 -1
  36. package/dist/host-D5kZAhga.mjs +0 -478
  37. package/dist/host-D5kZAhga.mjs.map +0 -1
  38. package/dist/relation-values-B0JhHBjZ.mjs +0 -232
  39. package/dist/relation-values-B0JhHBjZ.mjs.map +0 -1
  40. package/dist/runtime-C3bstvB8.d.mts +0 -465
  41. package/dist/runtime-C3bstvB8.d.mts.map +0 -1
  42. package/dist/runtime-CWC5y95G.mjs +0 -2907
  43. package/dist/runtime-CWC5y95G.mjs.map +0 -1
@@ -1,66 +1,62 @@
1
- # Eidos File developer platform
1
+ # Eidos 1.0 implementation boundary
2
2
 
3
- This document records the implementation audit behind the public package
4
- boundary. It describes current code, not a future app SDK.
3
+ This package implements the frozen four-layer Eidos 1.0 contract. The English
4
+ documents in [`docs/specs`](../../docs/specs/README.md) are normative; the
5
+ Chinese documents are item-by-item references.
5
6
 
6
- ## What “file” means in Eidos today
7
+ | Layer | Implementation owner | May depend on | Must not own |
8
+ | ----------- | ----------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------ |
9
+ | File Format | canonical DDL, values and validation in this package | SQLite 3.45 baseline | Host lifecycle or presentation |
10
+ | Runtime | `Runtime` / `EidosRuntimeService` | `ConnectionPort`, Clock, Entropy, Cancellation | paths, handles, publication authority |
11
+ | Adapter | Connection ports, Adapter transport, product `HostServices` | Runtime factory/service | alternate File semantics |
12
+ | UI | `EidosUIKernel` and trusted renderers | `RuntimeClient`, `HostServices` | SQL, format decoding, local canonical undo |
7
13
 
8
- | Area | Current responsibility | Public-platform decision |
9
- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
10
- | File-based Space | A folder is the source of truth; `@eidos.space/file-space` reads, writes, watches, previews, and indexes Markdown and binary files | Remains a Node/Desktop Space runtime. It is not part of the Eidos File SDK |
11
- | File handlers | Installed extension contributions select editors for Markdown, code, media, and other paths | Remains the Eidos extension system. Public React views use a separate trusted registry |
12
- | Eidos File | A `.eidos` SQLite database with portable tables, fields, views, relations, queries, and mutations | Owned by `@eidos.space/eidos-file` |
13
- | Browser editor | File picker/import fallback, SQLite WASM, save state, conflict checks, and recovery | Reusable lifecycle moved behind `@eidos.space/eidos-file/browser` and `EidosFileSession` |
14
- | Desktop editor | File Space services and Electron-owned filesystem access provide an app-specific data source | Stays behind the same public `EidosFileDataSource`; IPC is never public |
15
- | React editor | Grid, Gallery, Kanban, view routing, selection, commands, and host theme | Owned by `@eidos.space/eidos-file-ui` |
14
+ ## Connection conformance
16
15
 
17
- ## Coupling audit
16
+ Both reference SQLite implementations expose EA-Connection-1.0 tagged values,
17
+ transactions, snapshots, cancellation and limits:
18
18
 
19
- - `@eidos.space/eidos-file` main entry is framework-agnostic and browser-safe.
20
- `better-sqlite3` and SQLite WASM are isolated to explicit subpaths.
21
- - `@eidos.space/eidos-file-ui` depends on React and DOM APIs, but not Eidos
22
- routes, Zustand stores, Electron, or application aliases.
23
- - `@eidos.space/file-space` uses Node filesystem capabilities and remains
24
- unsuitable for browser embedding.
25
- - Existing Space file handlers receive Eidos extension context and app-owned
26
- filesystem APIs. They are not interchangeable with trusted React views.
27
- - Asset previews are host resolvers. Views receive URLs, never unrestricted
28
- filesystem access.
19
+ - Browser: `SQLiteWasmConnectionPort`, hosted beside Runtime in a Dedicated
20
+ Worker and reached through Adapter transport.
21
+ - Desktop: `BetterSqlite3ConnectionPort`, kept behind the trusted main-process
22
+ composition.
29
23
 
30
- ## Minimal public model
24
+ Neither port exposes SQLite to UI. Both run the mandatory SQLite/JSON1/STRICT/
25
+ RETURNING/int64/scalar-function probes before Runtime opens a File.
31
26
 
32
- ```text
33
- EidosFileHandle ──read/write/CAS──> EidosFileSession
34
- │
35
- EidosFileRuntimeAdapter
36
- │
37
- EidosFileDataSource
38
- │
39
- React View Host
40
- ```
27
+ ## Runtime conformance
41
28
 
42
- The handle owns descriptor identity, permissions, and persistence. The runtime
43
- owns format validation and data semantics. The session owns asynchronous
44
- lifecycle and recovery. The view host owns selection, local state, commands,
45
- theme, and rendering.
29
+ `Runtime.open` verifies Adapter capabilities and File identity. A readwrite
30
+ binding additionally verifies Writer structural preconditions. `Runtime.create`
31
+ executes the exact File DDL in the Adapter-owned outer transaction and creates
32
+ no default Table.
46
33
 
47
- ## First-release scope
34
+ The public service uses Field IDs and logical values only. Reads are columnar
35
+ and revision-bound. Cursors are authenticated, stateless keyset boundaries.
36
+ Aggregates and groups use exact typed equality/order and deterministic numeric
37
+ arithmetic. Writes validate the complete operation before mutation, increment
38
+ revision once only when canonical state changes, and report every affected
39
+ Table/Row. The prepared-commit transport barrier runs before the outer COMMIT.
48
40
 
49
- Included:
41
+ Capabilities are truthful. Optional public methods are absent when their bit is
42
+ false; a disabled non-optional operation rejects `unsupported`.
50
43
 
51
- - `.eidos` format validation, migration, query, paging, and mutation;
52
- - browser import, native picker, save, Save As, conflict, recovery, and cleanup;
53
- - Node/Electron `better-sqlite3` entry;
54
- - typed React provider, hooks, view host, Grid, optional Gallery/Kanban plugins,
55
- and trusted custom view registration;
56
- - light/dark theme tokens and precompiled standalone CSS.
44
+ ## Host and UI composition
57
45
 
58
- Out of scope:
46
+ Product code implements `HostServices` with opaque source/destination/session
47
+ tokens. It owns permission, recovery, CAS publication, conflicts, assets and
48
+ Runtime replacement. UI bootstraps by Host negotiation, Runtime negotiation,
49
+ snapshot and revision-bound schema paging. It invalidates generated page state
50
+ on revision/epoch change and never interprets File storage.
59
51
 
60
- - the complete Eidos app shell or Space navigation;
61
- - Markdown/Base format ownership and Base UI;
62
- - arbitrary File Space handlers or extension installation;
63
- - untrusted code execution, remote file upload, sync, collaboration, or auth;
64
- - hidden access to Eidos stores, routes, IPC, filesystem, or database singletons;
65
- - a generic document framework for formats that do not share Eidos File
66
- runtime semantics.
52
+ The older handle/session/data-source and editor component family remains for
53
+ compatibility with the pre-freeze demo. It is deliberately documented as a
54
+ legacy composition and is not evidence of EA-Host or EU profile conformance.
55
+
56
+ ## Interoperability verification
57
+
58
+ Conformance work must cover the same contract through Browser WASM and Desktop
59
+ better-sqlite3, plus Adapter transport and a mock Host/UI harness. API reports,
60
+ fixtures and implementation-facing docs are generated from the same public
61
+ surface. Frozen specifications are changed only for a demonstrated normative
62
+ defect, never to match an implementation shortcut.
package/README.md CHANGED
@@ -1,127 +1,94 @@
1
1
  # `@eidos.space/eidos-file`
2
2
 
3
- Headless runtime and host contracts for portable Eidos `.eidos` files.
3
+ Portable Eidos File 1.0 contracts and the reference headless Runtime.
4
4
 
5
- An Eidos File is a normal SQLite database containing portable table, field,
6
- view, and relation metadata. The package does not depend on the Eidos app,
7
- Zustand stores, routes, Electron IPC, or a database singleton.
5
+ The normative specifications are [`docs/specs`](../../docs/specs/README.md).
6
+ Implementations compose in one direction:
7
+
8
+ ```text
9
+ Eidos File 1.0 → Eidos Runtime 1.0 → Eidos Adapter 1.0 → Eidos UI 1.0
10
+ ```
11
+
12
+ The File is an ordinary SQLite application file. Runtime alone owns format
13
+ semantics. Adapters own SQLite execution, transport, persistence and Host
14
+ authority. UI receives only `RuntimeClient` and `HostServices`; it never
15
+ receives SQL, a database, a path or a native file handle.
8
16
 
9
17
  ## Install
10
18
 
11
19
  ```bash
12
- pnpm add @eidos.space/eidos-file@0.1.0
20
+ pnpm add @eidos.space/eidos-file@1.0.0
13
21
  ```
14
22
 
15
- Add `@eidos.space/eidos-file-ui@0.1.0` when rendering React views.
23
+ Add `@eidos.space/eidos-file-ui` for the React Viewer binding.
16
24
 
17
- ## Browser host
25
+ ## Exact Runtime binding
18
26
 
19
- The browser entry includes a SQLite WASM runtime, native file picker adapter,
20
- copy-mode fallback, conflict detection, and IndexedDB recovery store.
27
+ `Runtime.create` initializes an empty `ConnectionPort`; `Runtime.open` validates
28
+ an existing one. Both return a public service plus a trusted Host-only bridge.
21
29
 
22
30
  ```ts
23
- import { EidosFileSession } from "@eidos.space/eidos-file"
24
31
  import {
25
- EidosFileBrowserRuntime,
26
- IndexedDbEidosFileRecoveryStore,
27
- openBrowserEidosFile,
28
- pickBrowserEidosFile,
29
- } from "@eidos.space/eidos-file/browser"
30
-
31
- const session = new EidosFileSession(
32
- new EidosFileBrowserRuntime(),
33
- new IndexedDbEidosFileRecoveryStore()
32
+ Runtime,
33
+ type ConnectionPort,
34
+ type RuntimeEnvironment,
35
+ } from "@eidos.space/eidos-file"
36
+
37
+ const binding = await Runtime.open(
38
+ connection satisfies ConnectionPort,
39
+ environment satisfies RuntimeEnvironment,
40
+ "readwrite",
41
+ { cancellation, deadlineMilliseconds: 30_000 }
34
42
  )
35
43
 
36
- const direct = await pickBrowserEidosFile()
37
- const imported = fileInput.files?.[0]
38
- ? await openBrowserEidosFile(fileInput.files[0])
39
- : null
40
- const handle = direct ?? imported
41
-
42
- if (handle) await session.open(handle)
44
+ const negotiated = await binding.service.negotiate(
45
+ { protocol: "eidos-runtime", versions: ["1.0"] },
46
+ { requestId: "negotiate" }
47
+ )
43
48
  ```
44
49
 
45
- SQLite WASM uses WebAssembly and top-level await. A Vite host should enable the
46
- same two standard plugins:
50
+ The service exposes the frozen columnar query, authenticated keyset cursor,
51
+ aggregate/group, validation and transactional mutation contracts. Integer
52
+ values are decimal strings at public boundaries; JSON Field values are RFC
53
+ 8785 JCS text strings. Optional undo/events/CSV methods exist exactly when the
54
+ matching negotiated capability is true.
47
55
 
48
- ```ts
49
- import { defineConfig } from "vite"
50
- import topLevelAwait from "vite-plugin-top-level-await"
51
- import wasm from "vite-plugin-wasm"
52
-
53
- export default defineConfig({
54
- plugins: [wasm(), topLevelAwait()],
55
- optimizeDeps: { exclude: ["@sqlite.org/sqlite-wasm"] },
56
- })
57
- ```
56
+ ## Adapter profiles
58
57
 
59
- Call `session.markDirty()` after a committed mutation. `checkpoint()` stores a
60
- recoverable working copy. `save()` exports an integrity-checked database and
61
- performs a compare-and-swap write against the revision observed at open time.
62
-
63
- ```ts
64
- import { EidosFileHostError } from "@eidos.space/eidos-file"
65
-
66
- session.markDirty()
67
- await session.checkpoint()
68
-
69
- try {
70
- await session.save()
71
- } catch (error) {
72
- if (error instanceof EidosFileHostError && error.code === "conflict") {
73
- // Offer reload, forced overwrite, or Save As. Do not silently choose.
74
- }
75
- }
76
- ```
58
+ - `BetterSqlite3ConnectionPort` in `@eidos.space/eidos-file/better-sqlite3`
59
+ implements the Desktop EA-Connection binding.
60
+ - `SQLiteWasmConnectionPort` in `@eidos.space/eidos-file/browser` implements
61
+ the Browser Worker EA-Connection binding using the same conformance contract.
62
+ - `AdapterTransportServer` and `AdapterTransportRuntimeClient` implement the
63
+ Eidos Adapter 1.0 structured-clone transport, including sequence binding,
64
+ cancellation, attachment limits and the prepared-commit acknowledgement
65
+ barrier.
77
66
 
78
- Chromium-based browsers can write to the original file after user permission.
79
- Other browsers open an imported copy; hosts can offer Save As when supported or
80
- `downloadEidosFile()` as the fallback. File bytes stay in the browser.
67
+ The browser-conforming composition keeps SQLite and Runtime in a Dedicated
68
+ Worker. Window receives only the transported `RuntimeClient`; SQLite, File
69
+ bytes, and trusted Host authority remain outside UI.
81
70
 
82
- ## Node and Electron
71
+ ## File rules implemented here
83
72
 
84
- The optional `better-sqlite3` entry owns native file access. The main entry
85
- remains browser-safe and works against the small `EidosFileConnection`
86
- interface.
73
+ - canonical File DDL, `STRICT` user tables and File-owned triggers;
74
+ - lowercase hyphenated UUIDv7 identity;
75
+ - exact physical naming, rename and conversion behavior;
76
+ - canonical date/datetime, JSON, list, File and Relation values;
77
+ - virtual Formula, Lookup and inverse-Relation projection;
78
+ - revision, no-op mutation, delete policy and cache invalidation semantics;
79
+ - cumulative identity/structural/content/semantic/full validation.
87
80
 
88
- ```ts
89
- import { createEidosFile } from "@eidos.space/eidos-file/better-sqlite3"
81
+ Unsupported pre-1.0 draft schemas are rejected rather than guessed or
82
+ silently migrated.
90
83
 
91
- const file = createEidosFile("tasks.eidos", {
92
- title: "Tasks",
93
- defaultTable: { name: "Tasks" },
94
- })
84
+ ## Verification
95
85
 
96
- file.insertRow(file.info().defaultTableId!, { title: "Ship Eidos File" })
97
- file.close()
86
+ ```bash
87
+ pnpm --filter @eidos.space/eidos-file typecheck
88
+ pnpm --filter @eidos.space/eidos-file typecheck:public
89
+ pnpm --filter @eidos.space/eidos-file build
90
+ pnpm --filter @eidos.space/eidos-file api:check
98
91
  ```
99
92
 
100
- ## Public boundaries
101
-
102
- - `EidosFileDescriptor` is adapter-owned identity, metadata, size, and an
103
- opaque revision token.
104
- - `EidosFileHandle` owns reading, permissions, and optional verified writes.
105
- - `EidosFileRuntimeAdapter` turns bytes into an `EidosFileDocument`.
106
- - `EidosFileDataSource` is the async paging and mutation contract consumed by
107
- views.
108
- - `EidosFileSession` owns open, dirty, saving, conflict, error, recovery, and
109
- cleanup states.
110
- - `EidosFileHandlerRegistry` matches file types. It does not install or execute
111
- extensions.
112
-
113
- See [DEVELOPER_PLATFORM.md](./DEVELOPER_PLATFORM.md) for the audited product
114
- boundary and first-release scope.
115
-
116
- ## Security
117
-
118
- Adapters are the authority boundary. A view never receives SQLite, a native
119
- file handle, the browser picker, Electron IPC, or host application state.
120
- React views are trusted application code, not sandboxed extensions. A host must
121
- review and statically import them just like any other dependency.
122
-
123
- ## Format notes
124
-
125
- Files remain valid SQLite databases and can be inspected with ordinary SQLite
126
- tools. Gallery and Kanban query indexes are disposable SQLite indexes maintained
127
- by the runtime; they are not Eidos metadata or user data.
93
+ The package is framework-agnostic. React bindings live in
94
+ `@eidos.space/eidos-file-ui`.