@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 +21 -0
- package/README.md +21 -2
- package/dist/index.d.ts +66 -0
- package/dist/index.js +152 -0
- package/package.json +34 -3
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
|
-
#
|
|
1
|
+
# `@sorbetai/artifacts`
|
|
2
2
|
|
|
3
|
-
|
|
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).
|
package/dist/index.d.ts
ADDED
|
@@ -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.
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
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
|
}
|