@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.
- package/DEVELOPER_PLATFORM.md +49 -53
- package/README.md +66 -99
- package/dist/adapter-contract-B3p-48Yb.d.mts +1149 -0
- package/dist/adapter-contract-B3p-48Yb.d.mts.map +1 -0
- package/dist/better-sqlite3.d.mts +64 -3
- package/dist/better-sqlite3.d.mts.map +1 -1
- package/dist/better-sqlite3.mjs +387 -14
- package/dist/better-sqlite3.mjs.map +1 -1
- package/dist/browser.d.mts +4 -3
- package/dist/browser.d.mts.map +1 -1
- package/dist/browser.mjs +30 -11
- package/dist/browser.mjs.map +1 -1
- package/dist/csv-WEud-i_H.mjs +376 -0
- package/dist/csv-WEud-i_H.mjs.map +1 -0
- package/dist/csv.d.mts +1 -1
- package/dist/csv.d.mts.map +1 -1
- package/dist/csv.mjs +1 -248
- package/dist/index.d.mts +312 -18
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +3237 -4
- package/dist/index.mjs.map +1 -0
- package/dist/runtime-CMdfE7Gx.mjs +5476 -0
- package/dist/runtime-CMdfE7Gx.mjs.map +1 -0
- package/dist/runtime-DCo5E0Kr.d.mts +668 -0
- package/dist/runtime-DCo5E0Kr.d.mts.map +1 -0
- package/dist/select-options-DihMTuoa.mjs +518 -0
- package/dist/select-options-DihMTuoa.mjs.map +1 -0
- package/dist/sqlite-wasm-B86yaLG6.mjs +2000 -0
- package/dist/sqlite-wasm-B86yaLG6.mjs.map +1 -0
- package/dist/temporal-CVzLU63l.d.mts +517 -0
- package/dist/temporal-CVzLU63l.d.mts.map +1 -0
- package/package.json +2 -3
- package/dist/csv.mjs.map +0 -1
- package/dist/host-CqP1MeMK.d.mts +0 -213
- package/dist/host-CqP1MeMK.d.mts.map +0 -1
- package/dist/host-D5kZAhga.mjs +0 -478
- package/dist/host-D5kZAhga.mjs.map +0 -1
- package/dist/relation-values-B0JhHBjZ.mjs +0 -232
- package/dist/relation-values-B0JhHBjZ.mjs.map +0 -1
- package/dist/runtime-C3bstvB8.d.mts +0 -465
- package/dist/runtime-C3bstvB8.d.mts.map +0 -1
- package/dist/runtime-CWC5y95G.mjs +0 -2907
- package/dist/runtime-CWC5y95G.mjs.map +0 -1
package/DEVELOPER_PLATFORM.md
CHANGED
|
@@ -1,66 +1,62 @@
|
|
|
1
|
-
# Eidos
|
|
1
|
+
# Eidos 1.0 implementation boundary
|
|
2
2
|
|
|
3
|
-
This
|
|
4
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
16
|
+
Both reference SQLite implementations expose EA-Connection-1.0 tagged values,
|
|
17
|
+
transactions, snapshots, cancellation and limits:
|
|
18
18
|
|
|
19
|
-
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
|
|
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
|
-
|
|
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
|
-
|
|
33
|
-
EidosFileHandle ──read/write/CAS──> EidosFileSession
|
|
34
|
-
│
|
|
35
|
-
EidosFileRuntimeAdapter
|
|
36
|
-
│
|
|
37
|
-
EidosFileDataSource
|
|
38
|
-
│
|
|
39
|
-
React View Host
|
|
40
|
-
```
|
|
27
|
+
## Runtime conformance
|
|
41
28
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
61
|
-
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
|
|
3
|
+
Portable Eidos File 1.0 contracts and the reference headless Runtime.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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@
|
|
20
|
+
pnpm add @eidos.space/eidos-file@1.0.0
|
|
13
21
|
```
|
|
14
22
|
|
|
15
|
-
Add `@eidos.space/eidos-file-ui
|
|
23
|
+
Add `@eidos.space/eidos-file-ui` for the React Viewer binding.
|
|
16
24
|
|
|
17
|
-
##
|
|
25
|
+
## Exact Runtime binding
|
|
18
26
|
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
46
|
-
|
|
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
|
-
|
|
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
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
##
|
|
71
|
+
## File rules implemented here
|
|
83
72
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
|
|
89
|
-
|
|
81
|
+
Unsupported pre-1.0 draft schemas are rejected rather than guessed or
|
|
82
|
+
silently migrated.
|
|
90
83
|
|
|
91
|
-
|
|
92
|
-
title: "Tasks",
|
|
93
|
-
defaultTable: { name: "Tasks" },
|
|
94
|
-
})
|
|
84
|
+
## Verification
|
|
95
85
|
|
|
96
|
-
|
|
97
|
-
file
|
|
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
|
-
|
|
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`.
|