@sorbetai/artifacts 0.0.0-stage → 0.1.0-alpha.16

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Loro LLC.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,22 @@
1
- # Temporary Holding Version
1
+ # `@sorbetai/artifacts`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Storage-neutral contracts for Sorbet artifact objects. Stores create object identity;
4
+ hosts own concrete storage, retention and access policy. References are
5
+ `{ id: string, byteLength: number }` and remain usable without the producing Session.
6
+
7
+ | Surface | Contract |
8
+ | ----------------------- | -------------------------------------------------------------------------- |
9
+ | `ArtifactStore.put` | Publish bytes durably before returning their reference |
10
+ | `ArtifactStore.putText` | Optional streaming text publication with the same result |
11
+ | `ArtifactStore.read` | Read the full object or requested byte range; return undefined when absent |
12
+ | Text helpers | Preserve UTF-8 boundaries and bounded lookahead for pages and queries |
13
+
14
+ A caller transfers the reference to consumers, which use it directly. Independent
15
+ puts may store equal bytes. Reuse an existing reference to reuse an object.
16
+ Range reads perform I/O for the requested window; adapters handle short reads and
17
+ observe cancellation. The Node adapter lives in
18
+ [FileArtifactStore](../node-agent/src/artifacts/file-store.ts).
19
+
20
+ Runtime records output references in durable facts and maintains a Session index
21
+ for artifact origins and paging. See [Tool output](../runtime/src/tools/README.md)
22
+ and [ADR-0085](../../docs/adr/0085-trusted-core-ownership.md).
@@ -0,0 +1,66 @@
1
+ import * as s from "@earendil-works/pi-schema";
2
+
3
+ //#region src/contracts.d.ts
4
+ declare const ArtifactRefSchema: s.Schema<{
5
+ id: string;
6
+ byteLength: number;
7
+ }>;
8
+ type ArtifactRef = Readonly<s.Static<typeof ArtifactRefSchema>>;
9
+ //#endregion
10
+ //#region src/store.d.ts
11
+ declare const ArtifactReadRangeSchema: s.Schema<{
12
+ offset: number;
13
+ length: number;
14
+ }>;
15
+ type ArtifactReadRange = Readonly<s.Static<typeof ArtifactReadRangeSchema>>;
16
+ interface ArtifactReadOptions {
17
+ readonly range?: ArtifactReadRange;
18
+ readonly signal?: AbortSignal;
19
+ }
20
+ /**
21
+ * Storage owns each published object. A reference is available only after durable
22
+ * publication; a range reads only the requested window. Reads observe cancellation.
23
+ */
24
+ interface ArtifactStore {
25
+ put(bytes: Uint8Array): Promise<ArtifactRef>;
26
+ /**
27
+ * Stores the exact UTF-8 encoding of the concatenated chunks without requiring
28
+ * the caller to materialize the complete byte array. Implementations may omit
29
+ * this capability; callers must fall back to `put` when it is unavailable.
30
+ */
31
+ putText?(chunks: Iterable<string>): Promise<ArtifactRef>;
32
+ read(ref: ArtifactRef, options?: ArtifactReadOptions): Promise<Uint8Array | undefined>;
33
+ }
34
+ //#endregion
35
+ //#region src/text.d.ts
36
+ declare const ArtifactTextReadOptionsSchema: s.Schema<{
37
+ offset?: number | undefined;
38
+ maxBytes?: number | undefined;
39
+ }>;
40
+ declare const ArtifactTextQueryOptionsSchema: s.Schema<{
41
+ query: string;
42
+ offset?: number | undefined;
43
+ maxScanBytes?: number | undefined;
44
+ maxMatches?: number | undefined;
45
+ }>;
46
+ type ArtifactTextReadOptions = Readonly<s.Static<typeof ArtifactTextReadOptionsSchema>>;
47
+ type ArtifactTextQueryOptions = Readonly<s.Static<typeof ArtifactTextQueryOptionsSchema>>;
48
+ interface ArtifactTextPage {
49
+ readonly offset: number;
50
+ readonly bytesRead: number;
51
+ readonly text: string;
52
+ readonly nextOffset?: number;
53
+ }
54
+ interface ArtifactTextQueryMatch {
55
+ readonly characterOffset: number;
56
+ readonly text: string;
57
+ }
58
+ interface ArtifactTextQueryResult {
59
+ readonly query: string;
60
+ readonly scanned: Omit<ArtifactTextPage, 'text'>;
61
+ readonly matches: readonly ArtifactTextQueryMatch[];
62
+ }
63
+ declare function readArtifactTextPage(store: ArtifactStore, input: ArtifactRef, optionsInput?: ArtifactTextReadOptions, signal?: AbortSignal): Promise<ArtifactTextPage | undefined>;
64
+ declare function queryArtifactText(store: ArtifactStore, input: ArtifactRef, optionsInput: ArtifactTextQueryOptions, signal?: AbortSignal): Promise<ArtifactTextQueryResult | undefined>;
65
+ //#endregion
66
+ export { type ArtifactReadOptions, type ArtifactReadRange, ArtifactReadRangeSchema, type ArtifactRef, ArtifactRefSchema, type ArtifactStore, type ArtifactTextPage, type ArtifactTextQueryMatch, type ArtifactTextQueryOptions, type ArtifactTextQueryResult, type ArtifactTextReadOptions, queryArtifactText, readArtifactTextPage };
package/dist/index.js ADDED
@@ -0,0 +1,152 @@
1
+ import * as s from "@earendil-works/pi-schema";
2
+ import { decode } from "@sorbetai/schema";
3
+ import { escapeRegExp } from "es-toolkit";
4
+
5
+ //#region src/contracts.ts
6
+ const ArtifactRefSchema = s.obj({
7
+ id: s.str({
8
+ minLength: 1,
9
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._-]*$"
10
+ }),
11
+ byteLength: s.int({ minimum: 0 })
12
+ }, { open: false });
13
+
14
+ //#endregion
15
+ //#region src/store.ts
16
+ const ArtifactReadRangeSchema = s.obj({
17
+ offset: s.int({ minimum: 0 }),
18
+ length: s.int({ minimum: 1 })
19
+ }, { open: false });
20
+
21
+ //#endregion
22
+ //#region src/text.ts
23
+ const MAX_TEXT_PAGE_BYTES = 64 * 1024;
24
+ const MAX_QUERY_SCAN_BYTES = 256 * 1024;
25
+ const ArtifactTextReadOptionsSchema = s.obj({
26
+ offset: s.opt(s.int({ minimum: 0 })),
27
+ maxBytes: s.opt(s.int({
28
+ minimum: 4,
29
+ maximum: MAX_TEXT_PAGE_BYTES
30
+ }))
31
+ }, { open: false });
32
+ const ArtifactTextQueryOptionsSchema = s.obj({
33
+ query: s.str({
34
+ minLength: 1,
35
+ pattern: "\\S"
36
+ }),
37
+ offset: s.opt(s.int({ minimum: 0 })),
38
+ maxScanBytes: s.opt(s.int({
39
+ minimum: 4,
40
+ maximum: MAX_QUERY_SCAN_BYTES
41
+ })),
42
+ maxMatches: s.opt(s.int({
43
+ minimum: 1,
44
+ maximum: 20
45
+ }))
46
+ }, { open: false });
47
+ async function readArtifactTextPage(store, input, optionsInput = {}, signal) {
48
+ const ref = decode(ArtifactRefSchema, input);
49
+ const options = decode(ArtifactTextReadOptionsSchema, optionsInput);
50
+ return readTextWindow(store, ref, options.offset ?? 0, options.maxBytes ?? 16 * 1024, signal);
51
+ }
52
+ async function readTextWindow(store, ref, offset, maxBytes, signal) {
53
+ if (offset > ref.byteLength) throw new RangeError(`Artifact offset exceeds ${ref.byteLength}`);
54
+ const bytes = await store.read(ref, {
55
+ range: {
56
+ offset,
57
+ length: maxBytes + 3
58
+ },
59
+ signal
60
+ });
61
+ if (bytes === void 0) return;
62
+ const skippedBytes = offset === 0 ? 0 : leadingUtf8ContinuationLength(bytes);
63
+ const pageOffset = offset + skippedBytes;
64
+ const pageBytes = bytes.subarray(skippedBytes, skippedBytes + maxBytes);
65
+ const hasMore = pageOffset + pageBytes.byteLength < ref.byteLength;
66
+ const completeLength = hasMore ? completeUtf8PrefixLength(pageBytes) : pageBytes.byteLength;
67
+ if (hasMore && completeLength === 0) throw new RangeError("Artifact page is too small to contain one UTF-8 character");
68
+ const text = new TextDecoder("utf-8", { fatal: true }).decode(pageBytes.subarray(0, completeLength));
69
+ const nextOffset = pageOffset + completeLength < ref.byteLength ? pageOffset + completeLength : void 0;
70
+ const page = {
71
+ offset: pageOffset,
72
+ bytesRead: completeLength,
73
+ text
74
+ };
75
+ return nextOffset === void 0 ? page : {
76
+ ...page,
77
+ nextOffset
78
+ };
79
+ }
80
+ async function queryArtifactText(store, input, optionsInput, signal) {
81
+ const ref = decode(ArtifactRefSchema, input);
82
+ const options = decode(ArtifactTextQueryOptionsSchema, optionsInput);
83
+ const query = options.query.trim();
84
+ const maxScanBytes = options.maxScanBytes ?? MAX_QUERY_SCAN_BYTES;
85
+ const readAhead = await readTextWindow(store, ref, options.offset ?? 0, maxScanBytes + utf8Length(query), signal);
86
+ if (readAhead === void 0) return;
87
+ const scanned = utf8PrefixWithin(readAhead, maxScanBytes);
88
+ const matcher = new RegExp(escapeRegExp(query), "giu");
89
+ const maxMatches = options.maxMatches ?? 8;
90
+ const matches = [];
91
+ let lastMatchEnd;
92
+ let hasMoreMatches = false;
93
+ for (let match = matcher.exec(readAhead.text); match !== null; match = matcher.exec(readAhead.text)) {
94
+ const matchAt = match.index;
95
+ if (matchAt >= scanned.characterLength) break;
96
+ if (matches.length === maxMatches) {
97
+ hasMoreMatches = true;
98
+ break;
99
+ }
100
+ const matchEnd = matchAt + match[0].length;
101
+ const contextStart = Math.max(0, matchAt - 160);
102
+ const contextEnd = Math.min(readAhead.text.length, matchEnd + 240);
103
+ matches.push({
104
+ characterOffset: matchAt,
105
+ text: readAhead.text.slice(contextStart, contextEnd)
106
+ });
107
+ lastMatchEnd = matchEnd;
108
+ }
109
+ const scanEvidence = {
110
+ offset: readAhead.offset,
111
+ bytesRead: scanned.byteLength
112
+ };
113
+ let nextOffset;
114
+ if (hasMoreMatches && lastMatchEnd !== void 0) nextOffset = readAhead.offset + utf8Length(readAhead.text.slice(0, lastMatchEnd));
115
+ else if (readAhead.offset + scanned.byteLength < ref.byteLength) nextOffset = readAhead.offset + scanned.byteLength;
116
+ return {
117
+ query,
118
+ scanned: nextOffset === void 0 ? scanEvidence : {
119
+ ...scanEvidence,
120
+ nextOffset
121
+ },
122
+ matches
123
+ };
124
+ }
125
+ function utf8PrefixWithin(page, maxBytes) {
126
+ const { read, written } = new TextEncoder().encodeInto(page.text, new Uint8Array(Math.min(page.bytesRead, maxBytes)));
127
+ return {
128
+ byteLength: written,
129
+ characterLength: read
130
+ };
131
+ }
132
+ function utf8Length(value) {
133
+ return new TextEncoder().encode(value).byteLength;
134
+ }
135
+ function leadingUtf8ContinuationLength(bytes) {
136
+ let length = 0;
137
+ while (length < Math.min(bytes.byteLength, 3) && (bytes[length] & 192) === 128) length += 1;
138
+ return length;
139
+ }
140
+ function completeUtf8PrefixLength(bytes) {
141
+ const minimum = Math.max(0, bytes.byteLength - 3);
142
+ for (let length = bytes.byteLength; length >= minimum; length -= 1) try {
143
+ new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length));
144
+ return length;
145
+ } catch {
146
+ continue;
147
+ }
148
+ return 0;
149
+ }
150
+
151
+ //#endregion
152
+ export { ArtifactReadRangeSchema, ArtifactRefSchema, queryArtifactText, readArtifactTextPage };
package/package.json CHANGED
@@ -1,6 +1,37 @@
1
1
  {
2
2
  "name": "@sorbetai/artifacts",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0-alpha.16",
4
+ "license": "MIT",
5
+ "description": "Immutable artifact storage contracts for Sorbet",
6
+ "type": "module",
7
+ "files": [
8
+ "dist"
9
+ ],
10
+ "exports": {
11
+ ".": {
12
+ "types": "./dist/index.d.ts",
13
+ "import": "./dist/index.js"
14
+ }
15
+ },
16
+ "dependencies": {
17
+ "es-toolkit": "^1.53.1",
18
+ "@earendil-works/pi-schema": "1.5.0",
19
+ "@sorbetai/schema": "0.1.0-alpha.16"
20
+ },
21
+ "devDependencies": {
22
+ "@types/node": "^24.2.1",
23
+ "tsdown": "0.15.12",
24
+ "vitest": "^3.2.4"
25
+ },
26
+ "repository": {
27
+ "type": "git",
28
+ "url": "git+https://github.com/LodyAI/sorbet-distribution.git"
29
+ },
30
+ "scripts": {
31
+ "build": "tsdown",
32
+ "clean": "rm -rf dist coverage .turbo",
33
+ "dev": "tsdown --watch",
34
+ "test": "vitest run --maxWorkers=1 --passWithNoTests",
35
+ "typecheck": "tsc --noEmit"
36
+ }
6
37
  }