@ai-dev-orchestrator/artifacts 0.1.1 → 0.1.2
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/README.md +6 -0
- package/dist/infrastructure/artifact-system/artifact-write-recovery.d.ts +12 -0
- package/dist/infrastructure/artifact-system/artifact-write-recovery.js +110 -0
- package/dist/infrastructure/artifact-system/disk-reader.js +23 -2
- package/dist/infrastructure/artifact-system/filesystem-artifact-store.d.ts +5 -7
- package/dist/infrastructure/artifact-system/filesystem-artifact-store.js +67 -83
- package/dist/infrastructure/artifact-system/inventory-manager.js +58 -23
- package/dist/infrastructure/artifact-system/version-manager.js +5 -8
- package/package.json +8 -8
package/README.md
CHANGED
|
@@ -51,3 +51,9 @@ src/
|
|
|
51
51
|
**Infrastructure -- Agreement Artifacts**:
|
|
52
52
|
|
|
53
53
|
- `DefaultAgreementGate`, `AgreementGenerator`, `DefaultAgreementValidator`
|
|
54
|
+
|
|
55
|
+
## Write and recovery boundaries
|
|
56
|
+
|
|
57
|
+
Stores sharing a resolved artifacts directory serialize version allocation, content, metadata and inventory writes within one process. Failed queued writes do not block later writes. Cross-process mutation requires the orchestrator run lock. Version discovery matches the complete artifact name/version suffix, so names with shared prefixes remain independent.
|
|
58
|
+
|
|
59
|
+
Inventory reads refresh from disk. Malformed/schema-invalid inventories and inconsistent reference fields raise `InventoryCorruptionError`; they are never silently replaced with an empty index. After stopping writers and inspecting content/metadata, explicitly call `InventoryManager.rebuild()` to rebuild the index from valid metadata. Content, metadata and inventory are separate durable writes, so a crash can leave orphan files or an index missing a committed pair. Inspect/repair orphan pairs with recovery's `ArtifactConsistencyChecker`, then rebuild the inventory; this is an explicit maintenance API, not automatic CLI recovery. Preserve a copy before destructive repair.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { ArtifactMetadata } from '@ai-dev-orchestrator/schemas';
|
|
2
|
+
import type { InventoryManager } from './inventory-manager';
|
|
3
|
+
/** Recover one prepared write under the run owner's shared operation queue. */
|
|
4
|
+
export declare class ArtifactWriteRecovery {
|
|
5
|
+
private readonly artifactsDir;
|
|
6
|
+
private readonly runId;
|
|
7
|
+
private readonly inventory;
|
|
8
|
+
private readonly pendingPath;
|
|
9
|
+
constructor(artifactsDir: string, runId: string, inventory: InventoryManager);
|
|
10
|
+
commit(content: string, metadata: ArtifactMetadata): Promise<void>;
|
|
11
|
+
recover(): Promise<void>;
|
|
12
|
+
}
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { rm } from 'node:fs/promises';
|
|
2
|
+
import { basename, join } from 'node:path';
|
|
3
|
+
import { isDeepStrictEqual } from 'node:util';
|
|
4
|
+
import { artifactMetadataSchema } from '@ai-dev-orchestrator/schemas';
|
|
5
|
+
import { parse, stringify } from 'yaml';
|
|
6
|
+
import { z } from 'zod/v4';
|
|
7
|
+
import { InventoryCorruptionError } from '../../domain/artifact-system/errors';
|
|
8
|
+
import { computeChecksum } from './checksum-engine';
|
|
9
|
+
import { fileExists, readContent, readMetadata } from './disk-reader';
|
|
10
|
+
import { atomicWrite, writeMetadata } from './disk-writer';
|
|
11
|
+
const pendingWriteSchema = z.object({
|
|
12
|
+
runId: z.string(),
|
|
13
|
+
content: z.string(),
|
|
14
|
+
metadata: artifactMetadataSchema.extend({
|
|
15
|
+
name: z
|
|
16
|
+
.string()
|
|
17
|
+
.min(1)
|
|
18
|
+
.refine((name) => basename(name) === name && name !== '.' && name !== '..'),
|
|
19
|
+
version: z.number().int().positive(),
|
|
20
|
+
sizeBytes: z.number().int().nonnegative(),
|
|
21
|
+
}),
|
|
22
|
+
});
|
|
23
|
+
/** Recover one prepared write under the run owner's shared operation queue. */
|
|
24
|
+
export class ArtifactWriteRecovery {
|
|
25
|
+
artifactsDir;
|
|
26
|
+
runId;
|
|
27
|
+
inventory;
|
|
28
|
+
pendingPath;
|
|
29
|
+
constructor(artifactsDir, runId, inventory) {
|
|
30
|
+
this.artifactsDir = artifactsDir;
|
|
31
|
+
this.runId = runId;
|
|
32
|
+
this.inventory = inventory;
|
|
33
|
+
this.pendingPath = join(artifactsDir, '.pending-write.yaml');
|
|
34
|
+
}
|
|
35
|
+
async commit(content, metadata) {
|
|
36
|
+
// A completed intent write is the point after which recovery finishes this version.
|
|
37
|
+
if (metadata.runId !== undefined && metadata.runId !== this.runId) {
|
|
38
|
+
throw new InventoryCorruptionError('Artifact run identity does not match the owning store');
|
|
39
|
+
}
|
|
40
|
+
const pending = pendingWriteSchema.parse({ runId: this.runId, content, metadata });
|
|
41
|
+
await atomicWrite(this.pendingPath, stringify(pending));
|
|
42
|
+
await this.recover();
|
|
43
|
+
}
|
|
44
|
+
async recover() {
|
|
45
|
+
if (!fileExists(this.pendingPath)) {
|
|
46
|
+
return;
|
|
47
|
+
}
|
|
48
|
+
const invalid = (detail) => new InventoryCorruptionError(`Cannot recover pending artifact write at ${this.pendingPath}: ${detail}. Preserve the record and reconcile the conflicting files before retrying`);
|
|
49
|
+
let pending;
|
|
50
|
+
try {
|
|
51
|
+
pending = pendingWriteSchema.safeParse(parse(readContent(this.pendingPath, {
|
|
52
|
+
type: 'run_manifest',
|
|
53
|
+
name: 'pending-write',
|
|
54
|
+
version: 0,
|
|
55
|
+
checksum: '',
|
|
56
|
+
})));
|
|
57
|
+
}
|
|
58
|
+
catch {
|
|
59
|
+
throw invalid('invalid YAML recovery record');
|
|
60
|
+
}
|
|
61
|
+
if (!pending.success) {
|
|
62
|
+
throw invalid('invalid recovery record');
|
|
63
|
+
}
|
|
64
|
+
const { content, metadata, runId } = pending.data;
|
|
65
|
+
if (runId !== this.runId ||
|
|
66
|
+
(metadata.runId !== undefined && metadata.runId !== this.runId) ||
|
|
67
|
+
metadata.checksum !== computeChecksum(content) ||
|
|
68
|
+
metadata.sizeBytes !== Buffer.byteLength(content, 'utf8')) {
|
|
69
|
+
throw invalid('run identity, checksum or size does not match the recovery record');
|
|
70
|
+
}
|
|
71
|
+
const { type, name, version, checksum } = metadata;
|
|
72
|
+
const ref = { type, name, version, checksum };
|
|
73
|
+
const contentPath = join(this.artifactsDir, type, `${name}_v${String(version)}.md`);
|
|
74
|
+
const metaPath = join(this.artifactsDir, type, `${name}_v${String(version)}.meta.yaml`);
|
|
75
|
+
const summary = {
|
|
76
|
+
ref,
|
|
77
|
+
type,
|
|
78
|
+
name,
|
|
79
|
+
version,
|
|
80
|
+
producedBy: metadata.producedBy,
|
|
81
|
+
createdAt: metadata.createdAt,
|
|
82
|
+
sizeBytes: metadata.sizeBytes,
|
|
83
|
+
};
|
|
84
|
+
const existing = this.inventory
|
|
85
|
+
.getInventory()
|
|
86
|
+
.artifacts.find((entry) => entry.type === type && entry.name === name && entry.version === version);
|
|
87
|
+
if (existing && !isDeepStrictEqual(existing, summary)) {
|
|
88
|
+
throw invalid('inventory summary conflict');
|
|
89
|
+
}
|
|
90
|
+
const hasContent = fileExists(contentPath);
|
|
91
|
+
const hasMetadata = fileExists(metaPath);
|
|
92
|
+
// Check all existing evidence before writing any missing file. Never overwrite a conflict.
|
|
93
|
+
if (hasContent && readContent(contentPath, ref) !== content) {
|
|
94
|
+
throw invalid('content conflict');
|
|
95
|
+
}
|
|
96
|
+
if (hasMetadata && !isDeepStrictEqual(readMetadata(metaPath, ref), metadata)) {
|
|
97
|
+
throw invalid('metadata conflict');
|
|
98
|
+
}
|
|
99
|
+
if (!hasContent) {
|
|
100
|
+
await atomicWrite(contentPath, content);
|
|
101
|
+
}
|
|
102
|
+
if (!hasMetadata) {
|
|
103
|
+
await writeMetadata(metaPath, metadata);
|
|
104
|
+
}
|
|
105
|
+
if (!existing) {
|
|
106
|
+
await this.inventory.addEntry(summary);
|
|
107
|
+
}
|
|
108
|
+
await rm(this.pendingPath);
|
|
109
|
+
}
|
|
110
|
+
}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
+
import { artifactMetadataSchema } from '@ai-dev-orchestrator/schemas';
|
|
2
3
|
import { parse } from 'yaml';
|
|
3
|
-
import { ArtifactNotFoundError } from '../../domain/artifact-system/errors';
|
|
4
|
+
import { ArtifactNotFoundError, InventoryCorruptionError, } from '../../domain/artifact-system/errors';
|
|
4
5
|
/** Read artifact content from disk. Throws ArtifactNotFoundError if the file does not exist. */
|
|
5
6
|
export function readContent(filePath, ref) {
|
|
6
7
|
if (!existsSync(filePath)) {
|
|
@@ -14,7 +15,27 @@ export function readMetadata(filePath, ref) {
|
|
|
14
15
|
throw new ArtifactNotFoundError(ref);
|
|
15
16
|
}
|
|
16
17
|
const content = readFileSync(filePath, 'utf8');
|
|
17
|
-
|
|
18
|
+
try {
|
|
19
|
+
// Older sidecars omitted predecessorRef; preserve their read compatibility.
|
|
20
|
+
const metadata = artifactMetadataSchema
|
|
21
|
+
.extend({
|
|
22
|
+
predecessorRef: artifactMetadataSchema.shape.predecessorRef.default(null),
|
|
23
|
+
})
|
|
24
|
+
.parse(parse(content));
|
|
25
|
+
if (metadata.type !== ref.type ||
|
|
26
|
+
metadata.name !== ref.name ||
|
|
27
|
+
metadata.version !== ref.version ||
|
|
28
|
+
!Number.isSafeInteger(metadata.version) ||
|
|
29
|
+
metadata.version < 1 ||
|
|
30
|
+
!Number.isSafeInteger(metadata.sizeBytes) ||
|
|
31
|
+
metadata.sizeBytes < 0) {
|
|
32
|
+
throw new Error('metadata identity or size is invalid');
|
|
33
|
+
}
|
|
34
|
+
return metadata;
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
throw new InventoryCorruptionError(`Invalid artifact metadata at ${filePath}; preserve and repair the sidecar before retrying`);
|
|
38
|
+
}
|
|
18
39
|
}
|
|
19
40
|
/** Check if a file exists on disk. */
|
|
20
41
|
export function fileExists(filePath) {
|
|
@@ -1,21 +1,19 @@
|
|
|
1
1
|
import type { ArtifactStore, ArtifactTypeValidator, OwnershipRegistry } from '@ai-dev-orchestrator/ports';
|
|
2
2
|
import type { Artifact, ArtifactInput, ArtifactInventory, ArtifactQuery, ArtifactRef, ArtifactType, IntegrityResult } from '@ai-dev-orchestrator/schemas';
|
|
3
|
-
/**
|
|
4
|
-
* Filesystem-backed artifact store using synchronous I/O.
|
|
5
|
-
*
|
|
6
|
-
* Sync operations are accepted here: artifacts are small text files written once
|
|
7
|
-
* and read infrequently, so async I/O adds complexity without measurable benefit.
|
|
8
|
-
* Async migration is deferred to S14 if profiling shows contention.
|
|
9
|
-
*/
|
|
3
|
+
/** Filesystem-backed artifact store with serialized writes within the run owner process. */
|
|
10
4
|
export declare class FilesystemArtifactStore implements ArtifactStore {
|
|
11
5
|
private readonly artifactsDir;
|
|
12
6
|
private readonly versionManager;
|
|
13
7
|
private readonly inventoryManager;
|
|
8
|
+
private readonly writeRecovery;
|
|
14
9
|
private readonly ownershipRegistry;
|
|
15
10
|
private readonly typeValidator;
|
|
16
11
|
constructor(runDir: string, runId: string, ownershipRegistry: OwnershipRegistry, typeValidator: ArtifactTypeValidator);
|
|
17
12
|
store(input: ArtifactInput): Promise<ArtifactRef>;
|
|
13
|
+
private withRunQueue;
|
|
14
|
+
private storeVersion;
|
|
18
15
|
get(ref: ArtifactRef): Promise<Artifact>;
|
|
16
|
+
private readArtifact;
|
|
19
17
|
getLatest(type: ArtifactType, name: string): Promise<Artifact | null>;
|
|
20
18
|
list(query: ArtifactQuery): Promise<ArtifactRef[]>;
|
|
21
19
|
history(type: ArtifactType, name: string): Promise<ArtifactRef[]>;
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import { join } from 'node:path';
|
|
1
|
+
import { join, resolve } from 'node:path';
|
|
2
2
|
import { ImmutabilityViolationError, OwnershipViolationError, TypeValidationError, } from '../../domain/artifact-system/errors';
|
|
3
|
+
import { ArtifactWriteRecovery } from './artifact-write-recovery';
|
|
3
4
|
import { computeChecksum, verifyChecksum } from './checksum-engine';
|
|
4
5
|
import { fileExists, readContent, readMetadata } from './disk-reader';
|
|
5
|
-
import { atomicWrite, writeMetadata } from './disk-writer';
|
|
6
6
|
import { InventoryManager } from './inventory-manager';
|
|
7
7
|
import { VersionManager } from './version-manager';
|
|
8
8
|
const FAIL_SAFE_ARTIFACT_TYPES = new Set([
|
|
@@ -13,27 +13,45 @@ const FAIL_SAFE_ARTIFACT_TYPES = new Set([
|
|
|
13
13
|
'verification',
|
|
14
14
|
'judge_decision',
|
|
15
15
|
]);
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
* and read infrequently, so async I/O adds complexity without measurable benefit.
|
|
21
|
-
* Async migration is deferred to S14 if profiling shows contention.
|
|
22
|
-
*/
|
|
16
|
+
// One run owner can dispatch several workers and construct more than one store. Keep version
|
|
17
|
+
// allocation, content/metadata writes and inventory updates in the same process in order.
|
|
18
|
+
const pendingWrites = new Map();
|
|
19
|
+
/** Filesystem-backed artifact store with serialized writes within the run owner process. */
|
|
23
20
|
export class FilesystemArtifactStore {
|
|
24
21
|
artifactsDir;
|
|
25
22
|
versionManager;
|
|
26
23
|
inventoryManager;
|
|
24
|
+
writeRecovery;
|
|
27
25
|
ownershipRegistry;
|
|
28
26
|
typeValidator;
|
|
29
27
|
constructor(runDir, runId, ownershipRegistry, typeValidator) {
|
|
30
28
|
this.artifactsDir = join(runDir, 'artifacts');
|
|
31
29
|
this.versionManager = new VersionManager(this.artifactsDir);
|
|
32
30
|
this.inventoryManager = new InventoryManager(runDir, runId);
|
|
31
|
+
this.writeRecovery = new ArtifactWriteRecovery(this.artifactsDir, runId, this.inventoryManager);
|
|
33
32
|
this.ownershipRegistry = ownershipRegistry;
|
|
34
33
|
this.typeValidator = typeValidator;
|
|
35
34
|
}
|
|
36
|
-
|
|
35
|
+
store(input) {
|
|
36
|
+
return this.withRunQueue(() => this.storeVersion(input));
|
|
37
|
+
}
|
|
38
|
+
withRunQueue(operation) {
|
|
39
|
+
const key = resolve(this.artifactsDir);
|
|
40
|
+
const predecessor = pendingWrites.get(key) ?? Promise.resolve();
|
|
41
|
+
const result = predecessor.then(async () => {
|
|
42
|
+
await this.writeRecovery.recover();
|
|
43
|
+
return operation();
|
|
44
|
+
});
|
|
45
|
+
const settled = result.then(() => undefined, () => undefined);
|
|
46
|
+
pendingWrites.set(key, settled);
|
|
47
|
+
void settled.then(() => {
|
|
48
|
+
if (pendingWrites.get(key) === settled) {
|
|
49
|
+
pendingWrites.delete(key);
|
|
50
|
+
}
|
|
51
|
+
});
|
|
52
|
+
return result;
|
|
53
|
+
}
|
|
54
|
+
async storeVersion(input) {
|
|
37
55
|
if (!this.ownershipRegistry.isAuthorized(input.producedBy, input.type)) {
|
|
38
56
|
const owner = this.ownershipRegistry.getOwner(input.type);
|
|
39
57
|
throw new OwnershipViolationError(input.producedBy, input.type, owner ?? 'unknown');
|
|
@@ -50,6 +68,8 @@ export class FilesystemArtifactStore {
|
|
|
50
68
|
}
|
|
51
69
|
}
|
|
52
70
|
}
|
|
71
|
+
// Fail before creating files when the existing index is known to be corrupt.
|
|
72
|
+
this.inventoryManager.getInventory();
|
|
53
73
|
const version = this.versionManager.nextVersion(input.type, input.name);
|
|
54
74
|
const existingPath = this.artifactContentPath(input.type, input.name, version);
|
|
55
75
|
if (fileExists(existingPath)) {
|
|
@@ -64,7 +84,6 @@ export class FilesystemArtifactStore {
|
|
|
64
84
|
const createdAt = new Date().toISOString();
|
|
65
85
|
const sizeBytes = Buffer.byteLength(input.content, 'utf8');
|
|
66
86
|
const ref = { type: input.type, name: input.name, version, checksum };
|
|
67
|
-
await atomicWrite(existingPath, input.content);
|
|
68
87
|
const metadata = {
|
|
69
88
|
type: input.type,
|
|
70
89
|
name: input.name,
|
|
@@ -77,22 +96,13 @@ export class FilesystemArtifactStore {
|
|
|
77
96
|
sizeBytes,
|
|
78
97
|
metadata: validationFailed ? { ...input.metadata, validationFailed: true } : input.metadata,
|
|
79
98
|
};
|
|
80
|
-
|
|
81
|
-
await writeMetadata(metaPath, metadata);
|
|
82
|
-
const summary = {
|
|
83
|
-
ref,
|
|
84
|
-
type: input.type,
|
|
85
|
-
name: input.name,
|
|
86
|
-
version,
|
|
87
|
-
producedBy: input.producedBy,
|
|
88
|
-
createdAt,
|
|
89
|
-
sizeBytes,
|
|
90
|
-
};
|
|
91
|
-
await this.inventoryManager.addEntry(summary);
|
|
99
|
+
await this.writeRecovery.commit(input.content, metadata);
|
|
92
100
|
return ref;
|
|
93
101
|
}
|
|
94
|
-
|
|
95
|
-
|
|
102
|
+
get(ref) {
|
|
103
|
+
return this.withRunQueue(() => Promise.resolve(this.readArtifact(ref)));
|
|
104
|
+
}
|
|
105
|
+
readArtifact(ref) {
|
|
96
106
|
const contentPath = this.artifactContentPath(ref.type, ref.name, ref.version);
|
|
97
107
|
const metaPath = this.artifactMetaPath(ref.type, ref.name, ref.version);
|
|
98
108
|
const content = readContent(contentPath, ref);
|
|
@@ -112,75 +122,49 @@ export class FilesystemArtifactStore {
|
|
|
112
122
|
};
|
|
113
123
|
}
|
|
114
124
|
getLatest(type, name) {
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
const contentPath = this.artifactContentPath(type, name, latest);
|
|
120
|
-
const metaPath = this.artifactMetaPath(type, name, latest);
|
|
121
|
-
const ref = { type, name, version: latest, checksum: '' };
|
|
122
|
-
const content = readContent(contentPath, ref);
|
|
123
|
-
const meta = readMetadata(metaPath, ref);
|
|
124
|
-
return Promise.resolve({
|
|
125
|
-
ref: { type, name, version: latest, checksum: meta.checksum },
|
|
126
|
-
type: meta.type,
|
|
127
|
-
name: meta.name,
|
|
128
|
-
version: meta.version,
|
|
129
|
-
content,
|
|
130
|
-
checksum: meta.checksum,
|
|
131
|
-
producedBy: meta.producedBy,
|
|
132
|
-
predecessorRef: meta.predecessorRef ?? undefined,
|
|
133
|
-
createdAt: meta.createdAt,
|
|
134
|
-
sizeBytes: meta.sizeBytes,
|
|
135
|
-
metadata: meta.metadata,
|
|
125
|
+
return this.withRunQueue(() => {
|
|
126
|
+
const refs = this.inventoryManager.listRefs({ type, name });
|
|
127
|
+
const latest = refs.sort((a, b) => b.version - a.version).at(0);
|
|
128
|
+
return Promise.resolve(latest ? this.readArtifact(latest) : null);
|
|
136
129
|
});
|
|
137
130
|
}
|
|
138
131
|
list(query) {
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
132
|
+
return this.withRunQueue(() => {
|
|
133
|
+
let refs = this.inventoryManager.listRefs({
|
|
134
|
+
type: query.type,
|
|
135
|
+
name: query.name,
|
|
136
|
+
producedBy: query.producedBy,
|
|
137
|
+
});
|
|
138
|
+
const minVersion = query.minVersion;
|
|
139
|
+
if (minVersion !== undefined) {
|
|
140
|
+
refs = refs.filter((r) => r.version >= minVersion);
|
|
141
|
+
}
|
|
142
|
+
const maxVersion = query.maxVersion;
|
|
143
|
+
if (maxVersion !== undefined) {
|
|
144
|
+
refs = refs.filter((r) => r.version <= maxVersion);
|
|
145
|
+
}
|
|
146
|
+
return Promise.resolve(refs);
|
|
143
147
|
});
|
|
144
|
-
const minVersion = query.minVersion;
|
|
145
|
-
if (minVersion !== undefined) {
|
|
146
|
-
refs = refs.filter((r) => r.version >= minVersion);
|
|
147
|
-
}
|
|
148
|
-
const maxVersion = query.maxVersion;
|
|
149
|
-
if (maxVersion !== undefined) {
|
|
150
|
-
refs = refs.filter((r) => r.version <= maxVersion);
|
|
151
|
-
}
|
|
152
|
-
return Promise.resolve(refs);
|
|
153
148
|
}
|
|
154
149
|
history(type, name) {
|
|
155
|
-
|
|
156
|
-
const refs = [];
|
|
157
|
-
for (const version of versions) {
|
|
158
|
-
const metaPath = this.artifactMetaPath(type, name, version);
|
|
159
|
-
const dummyRef = { type, name, version, checksum: '' };
|
|
160
|
-
try {
|
|
161
|
-
const meta = readMetadata(metaPath, dummyRef);
|
|
162
|
-
refs.push({ type, name, version, checksum: meta.checksum });
|
|
163
|
-
}
|
|
164
|
-
catch {
|
|
165
|
-
refs.push(dummyRef);
|
|
166
|
-
}
|
|
167
|
-
}
|
|
168
|
-
return Promise.resolve(refs);
|
|
150
|
+
return this.withRunQueue(() => Promise.resolve(this.inventoryManager.listRefs({ type, name }).sort((a, b) => a.version - b.version)));
|
|
169
151
|
}
|
|
170
152
|
verify(ref) {
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
153
|
+
return this.withRunQueue(() => {
|
|
154
|
+
const contentPath = this.artifactContentPath(ref.type, ref.name, ref.version);
|
|
155
|
+
const content = readContent(contentPath, ref);
|
|
156
|
+
const actualChecksum = computeChecksum(content);
|
|
157
|
+
const valid = verifyChecksum(content, ref.checksum);
|
|
158
|
+
return Promise.resolve({
|
|
159
|
+
valid,
|
|
160
|
+
expectedChecksum: ref.checksum,
|
|
161
|
+
actualChecksum,
|
|
162
|
+
ref,
|
|
163
|
+
});
|
|
180
164
|
});
|
|
181
165
|
}
|
|
182
166
|
inventory() {
|
|
183
|
-
return Promise.resolve(this.inventoryManager.getInventory());
|
|
167
|
+
return this.withRunQueue(() => Promise.resolve(this.inventoryManager.getInventory()));
|
|
184
168
|
}
|
|
185
169
|
artifactContentPath(type, name, version) {
|
|
186
170
|
return join(this.artifactsDir, type, `${name}_v${String(version)}.md`);
|
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import { existsSync, readdirSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
-
import { INVENTORY_FILENAME, } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
import { INVENTORY_FILENAME, artifactSummarySchema, } from '@ai-dev-orchestrator/schemas';
|
|
4
4
|
import { parse, stringify } from 'yaml';
|
|
5
5
|
import { InventoryCorruptionError } from '../../domain/artifact-system/errors';
|
|
6
|
-
import {
|
|
6
|
+
import { computeChecksum } from './checksum-engine';
|
|
7
|
+
import { fileExists, readContent, readMetadata } from './disk-reader';
|
|
7
8
|
import { atomicWrite } from './disk-writer';
|
|
8
9
|
export class InventoryManager {
|
|
9
10
|
artifacts = [];
|
|
@@ -12,17 +13,20 @@ export class InventoryManager {
|
|
|
12
13
|
constructor(runDir, runId) {
|
|
13
14
|
this.runId = runId;
|
|
14
15
|
this.inventoryPath = join(runDir, INVENTORY_FILENAME);
|
|
15
|
-
this.loadFromDisk();
|
|
16
16
|
}
|
|
17
17
|
async addEntry(summary) {
|
|
18
|
+
// Another store owned by this run may have committed entries since construction.
|
|
19
|
+
this.loadFromDisk();
|
|
18
20
|
this.artifacts.push(summary);
|
|
19
21
|
await this.persist();
|
|
20
22
|
}
|
|
21
23
|
async removeEntry(ref) {
|
|
24
|
+
this.loadFromDisk();
|
|
22
25
|
this.artifacts = this.artifacts.filter((a) => !(a.ref.type === ref.type && a.ref.name === ref.name && a.ref.version === ref.version));
|
|
23
26
|
await this.persist();
|
|
24
27
|
}
|
|
25
28
|
getInventory() {
|
|
29
|
+
this.loadFromDisk();
|
|
26
30
|
const totalSizeBytes = this.artifacts.reduce((sum, a) => sum + a.sizeBytes, 0);
|
|
27
31
|
return {
|
|
28
32
|
runId: this.runId,
|
|
@@ -32,6 +36,7 @@ export class InventoryManager {
|
|
|
32
36
|
};
|
|
33
37
|
}
|
|
34
38
|
listRefs(query) {
|
|
39
|
+
this.loadFromDisk();
|
|
35
40
|
let filtered = this.artifacts;
|
|
36
41
|
if (query?.type) {
|
|
37
42
|
filtered = filtered.filter((a) => a.type === query.type);
|
|
@@ -45,8 +50,16 @@ export class InventoryManager {
|
|
|
45
50
|
return filtered.map((a) => a.ref);
|
|
46
51
|
}
|
|
47
52
|
async rebuild(artifactsDir) {
|
|
48
|
-
|
|
53
|
+
// Stage rebuilt entries locally. A failed scan must not replace the previous index.
|
|
54
|
+
const rebuilt = [];
|
|
55
|
+
if (fileExists(join(artifactsDir, '.pending-write.yaml'))) {
|
|
56
|
+
throw new InventoryCorruptionError('Pending artifact write must be recovered through the artifact store before rebuilding inventory');
|
|
57
|
+
}
|
|
49
58
|
if (!existsSync(artifactsDir)) {
|
|
59
|
+
if (this.getInventory().totalCount > 0) {
|
|
60
|
+
throw new InventoryCorruptionError(`Artifact directory is missing at ${artifactsDir}; restore the files before rebuilding the existing inventory`);
|
|
61
|
+
}
|
|
62
|
+
this.artifacts = rebuilt;
|
|
50
63
|
await this.persist();
|
|
51
64
|
return this.getInventory();
|
|
52
65
|
}
|
|
@@ -61,12 +74,21 @@ export class InventoryManager {
|
|
|
61
74
|
try {
|
|
62
75
|
const metaRef = {
|
|
63
76
|
type: typeDir,
|
|
64
|
-
name: '',
|
|
65
|
-
version:
|
|
77
|
+
name: metaFile.replace(/_v\d+\.meta\.yaml$/, ''),
|
|
78
|
+
version: Number(/_v(\d+)\.meta\.yaml$/.exec(metaFile)?.[1]),
|
|
66
79
|
checksum: '',
|
|
67
80
|
};
|
|
68
|
-
const
|
|
69
|
-
const
|
|
81
|
+
const meta = readMetadata(metaPath, metaRef);
|
|
82
|
+
const expectedName = `${meta.name}_v${String(meta.version)}.meta.yaml`;
|
|
83
|
+
const contentPath = join(typePath, `${meta.name}_v${String(meta.version)}.md`);
|
|
84
|
+
const content = readContent(contentPath, metaRef);
|
|
85
|
+
if (metaFile !== expectedName ||
|
|
86
|
+
meta.type !== typeDir ||
|
|
87
|
+
(meta.runId !== undefined && meta.runId !== this.runId) ||
|
|
88
|
+
meta.checksum !== computeChecksum(content) ||
|
|
89
|
+
meta.sizeBytes !== Buffer.byteLength(content, 'utf8')) {
|
|
90
|
+
throw new Error('metadata identity, content checksum or size mismatch');
|
|
91
|
+
}
|
|
70
92
|
const summary = {
|
|
71
93
|
ref: {
|
|
72
94
|
type: meta.type,
|
|
@@ -81,18 +103,20 @@ export class InventoryManager {
|
|
|
81
103
|
createdAt: meta.createdAt,
|
|
82
104
|
sizeBytes: meta.sizeBytes,
|
|
83
105
|
};
|
|
84
|
-
|
|
106
|
+
rebuilt.push(summary);
|
|
85
107
|
}
|
|
86
108
|
catch {
|
|
87
|
-
throw new InventoryCorruptionError(`
|
|
109
|
+
throw new InventoryCorruptionError(`Cannot rebuild from ${metaPath}: invalid metadata, identity or content. Preserve the current inventory and reconcile the artifact files before retrying`);
|
|
88
110
|
}
|
|
89
111
|
}
|
|
90
112
|
}
|
|
113
|
+
this.artifacts = rebuilt;
|
|
91
114
|
await this.persist();
|
|
92
115
|
return this.getInventory();
|
|
93
116
|
}
|
|
94
117
|
loadFromDisk() {
|
|
95
118
|
if (!fileExists(this.inventoryPath)) {
|
|
119
|
+
this.artifacts = [];
|
|
96
120
|
return;
|
|
97
121
|
}
|
|
98
122
|
try {
|
|
@@ -104,21 +128,32 @@ export class InventoryManager {
|
|
|
104
128
|
};
|
|
105
129
|
const content = readContent(this.inventoryPath, inventoryRef);
|
|
106
130
|
const data = parse(content);
|
|
107
|
-
if (Array.isArray(data.artifacts)) {
|
|
108
|
-
|
|
109
|
-
const r = raw;
|
|
110
|
-
const ref = r.ref ?? {
|
|
111
|
-
type: raw.type,
|
|
112
|
-
name: raw.name,
|
|
113
|
-
version: raw.version,
|
|
114
|
-
checksum: typeof r.checksum === 'string' ? r.checksum : '',
|
|
115
|
-
};
|
|
116
|
-
return { ...raw, ref };
|
|
117
|
-
});
|
|
131
|
+
if (!Array.isArray(data.artifacts)) {
|
|
132
|
+
throw new InventoryCorruptionError('Expected an artifacts array');
|
|
118
133
|
}
|
|
134
|
+
this.artifacts = data.artifacts.map((raw) => {
|
|
135
|
+
const r = raw;
|
|
136
|
+
const ref = r.ref ?? {
|
|
137
|
+
type: raw.type,
|
|
138
|
+
name: raw.name,
|
|
139
|
+
version: raw.version,
|
|
140
|
+
checksum: typeof r.checksum === 'string' ? r.checksum : '',
|
|
141
|
+
};
|
|
142
|
+
const summary = artifactSummarySchema.safeParse({ ...raw, ref });
|
|
143
|
+
if (!summary.success ||
|
|
144
|
+
ref.type !== raw.type ||
|
|
145
|
+
ref.name !== raw.name ||
|
|
146
|
+
ref.version !== raw.version) {
|
|
147
|
+
throw new InventoryCorruptionError('Invalid or inconsistent artifact summary');
|
|
148
|
+
}
|
|
149
|
+
return summary.data;
|
|
150
|
+
});
|
|
119
151
|
}
|
|
120
|
-
catch {
|
|
121
|
-
|
|
152
|
+
catch (error) {
|
|
153
|
+
if (error instanceof InventoryCorruptionError) {
|
|
154
|
+
throw error;
|
|
155
|
+
}
|
|
156
|
+
throw new InventoryCorruptionError(`Failed to parse inventory file: ${this.inventoryPath}`);
|
|
122
157
|
}
|
|
123
158
|
}
|
|
124
159
|
async persist() {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { existsSync, readdirSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
-
const VERSION_PATTERN =
|
|
3
|
+
const VERSION_PATTERN = /^_v(\d+)\.(?:md|meta\.yaml)$/;
|
|
4
4
|
/** Manages monotonically increasing version numbers for artifacts. */
|
|
5
5
|
export class VersionManager {
|
|
6
6
|
artifactsDir;
|
|
@@ -24,19 +24,16 @@ export class VersionManager {
|
|
|
24
24
|
return [];
|
|
25
25
|
}
|
|
26
26
|
const files = readdirSync(typeDir);
|
|
27
|
-
const versions =
|
|
27
|
+
const versions = new Set();
|
|
28
28
|
for (const file of files) {
|
|
29
29
|
if (!file.startsWith(`${name}_v`)) {
|
|
30
30
|
continue;
|
|
31
31
|
}
|
|
32
|
-
|
|
33
|
-
continue;
|
|
34
|
-
}
|
|
35
|
-
const match = VERSION_PATTERN.exec(file);
|
|
32
|
+
const match = VERSION_PATTERN.exec(file.slice(name.length));
|
|
36
33
|
if (match?.[1]) {
|
|
37
|
-
versions.
|
|
34
|
+
versions.add(Number(match[1]));
|
|
38
35
|
}
|
|
39
36
|
}
|
|
40
|
-
return versions.sort((a, b) => a - b);
|
|
37
|
+
return [...versions].sort((a, b) => a - b);
|
|
41
38
|
}
|
|
42
39
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ai-dev-orchestrator/artifacts",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -22,16 +22,16 @@
|
|
|
22
22
|
],
|
|
23
23
|
"dependencies": {
|
|
24
24
|
"write-file-atomic": "^8.0.0",
|
|
25
|
-
"yaml": "^2.9.
|
|
26
|
-
"zod": "^4.
|
|
27
|
-
"@ai-dev-orchestrator/ports": "0.1.
|
|
28
|
-
"@ai-dev-orchestrator/schemas": "0.1.
|
|
29
|
-
"@ai-dev-orchestrator/utils": "0.1.
|
|
25
|
+
"yaml": "^2.9.1",
|
|
26
|
+
"zod": "^4.6.7",
|
|
27
|
+
"@ai-dev-orchestrator/ports": "0.1.2",
|
|
28
|
+
"@ai-dev-orchestrator/schemas": "0.1.4",
|
|
29
|
+
"@ai-dev-orchestrator/utils": "0.1.2"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
|
-
"@types/node": "^26.
|
|
32
|
+
"@types/node": "^26.6.5",
|
|
33
33
|
"@types/write-file-atomic": "^4.0.3",
|
|
34
|
-
"fast-check": "^4.
|
|
34
|
+
"fast-check": "^4.10.2",
|
|
35
35
|
"vitest": "^4.1.11",
|
|
36
36
|
"@ai-dev-orchestrator/build-config": "0.1.1"
|
|
37
37
|
},
|