feat: inspect document upload journal from 0pt
CI (SIAX Cloud) / integration (push) Skipped
CI (SIAX Cloud) / sonar (push) Skipped
masterplan-lock / check (push) Successful in 7s
masterplan-lock / check (pull_request) Successful in 3s
CI (SIAX Cloud) / security (push) Successful in 22s
Security Scan (SIAX Cloud) / security (push) Successful in 23s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 29s
CI (SIAX Cloud) / quality (push) Successful in 1m20s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m6s
CI (SIAX Cloud) / security (pull_request) Successful in 14s
CI (SIAX Cloud) / sonar (pull_request) Skipped
CI (SIAX Cloud) / integration (pull_request) Successful in 47s

This commit is contained in:
2026-11-02 03:06:56 +01:00
parent 6594fccfa0
commit f79853d156
2 changed files with 117 additions and 20 deletions
+81 -19
View File
@@ -29,8 +29,50 @@ export class Doc0UploadOutcomeUnknownError extends Error {
}
}
export class Doc0InspectionUnavailableError extends Error {
constructor() {
super('DOC0 upload inspection could not be verified');
this.name = 'Doc0InspectionUnavailableError';
}
}
export interface Doc0InspectionInput {
tenantId: string;
projectId: string;
actorId: string;
requestId: string;
idempotencyKey: string;
sourceSha256: string;
sourceSizeBytes: number;
/** Original server-compatible fingerprint from a trusted, durable attempt manifest. */
requestFingerprint: string;
}
export type Doc0Inspection =
| { status: 'not_found' | 'in_progress' | 'reconciliation_required' }
| { status: 'completed_recorded'; documentId: string; versionId: string };
const MAX_RECEIPT_BYTES = 128 * 1024;
async function readBoundedJson(response: Response): Promise<unknown> {
if (!response.ok || !response.body) throw new Error('response unavailable');
const reader = response.body.getReader();
try {
const parts: Uint8Array[] = [];
let length = 0;
for (;;) {
const chunk = await reader.read();
if (chunk.done) break;
length += chunk.value.byteLength;
if (length > MAX_RECEIPT_BYTES) {
void reader.cancel().catch(() => undefined);
throw new Error('response too large');
}
parts.push(chunk.value);
}
return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts))) as unknown;
} finally { reader.releaseLock(); }
}
/**
* Internal client only. The caller must enforce verified tenant/project/actor
* permissions and data handling policy. The coordinated DOC0/N0D/ST0RE
@@ -114,27 +156,9 @@ export class Doc0UploadClient {
});
} catch { throw new Doc0UploadOutcomeUnknownError(); }
// Even a non-2xx response does not prove the write did not commit.
if (!response.ok || !response.body) throw new Doc0UploadOutcomeUnknownError();
let decoded: unknown;
let reader: ReadableStreamDefaultReader<Uint8Array>;
try { reader = response.body.getReader(); }
try { decoded = await readBoundedJson(response); }
catch { throw new Doc0UploadOutcomeUnknownError(); }
try {
const parts: Uint8Array[] = [];
let length = 0;
for (;;) {
const chunk = await reader.read();
if (chunk.done) break;
length += chunk.value.byteLength;
if (length > MAX_RECEIPT_BYTES) {
void reader.cancel().catch(() => undefined);
throw new Error('receipt too large');
}
parts.push(chunk.value);
}
decoded = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts))) as unknown;
} catch { throw new Doc0UploadOutcomeUnknownError(); }
finally { reader.releaseLock(); }
const data = decoded as {
document?: {
documentId?: unknown;
@@ -179,4 +203,42 @@ export class Doc0UploadClient {
pipelineStage: version.pipelineStage,
};
}
/**
* Observe only: neither `not_found` nor `completed_recorded` proves that
* an external write is absent, that storage is intact, or that extraction
* is complete. No automatic retry, settlement or customer route is wired.
*/
async inspect(input: Doc0InspectionInput): Promise<Doc0Inspection> {
if (![input.tenantId, input.projectId, input.actorId, input.requestId, input.idempotencyKey]
.every((value) => typeof value === 'string' && value.trim()) ||
input.projectId.length > 256 || input.idempotencyKey.length > 256 ||
!/^[0-9a-f]{64}$/.test(input.sourceSha256) || !/^[0-9a-f]{64}$/.test(input.requestFingerprint) ||
!Number.isSafeInteger(input.sourceSizeBytes) || input.sourceSizeBytes <= 0) {
throw new Error('Invalid DOC0 inspection input');
}
let result: unknown;
try {
const response = await this.fetchImpl(`${this.baseUrl}/v1/doc0/upload-intents/inspect`, {
method: 'POST', redirect: 'error', cache: 'no-store', signal: AbortSignal.timeout(this.options.timeoutMs ?? 120_000),
headers: { authorization: `Bearer ${this.options.serviceToken}`, 'content-type': 'application/json',
'x-tenant-id': input.tenantId, 'x-actor-id': input.actorId, 'x-request-id': input.requestId, 'x-idempotency-key': input.idempotencyKey },
body: JSON.stringify({ projectId: input.projectId, sourceSha256: input.sourceSha256,
sourceSizeBytes: input.sourceSizeBytes, requestFingerprint: input.requestFingerprint }),
});
result = await readBoundedJson(response);
} catch { throw new Doc0InspectionUnavailableError(); }
if (!result || typeof result !== 'object' || Array.isArray(result)) throw new Doc0InspectionUnavailableError();
const record = result as Record<string, unknown>;
if (typeof record.status === 'string' && ['not_found', 'in_progress', 'reconciliation_required'].includes(record.status) &&
Object.keys(record).length === 1) {
return { status: record.status as 'not_found' | 'in_progress' | 'reconciliation_required' };
}
if (record.status === 'completed_recorded' && Object.keys(record).length === 3 &&
typeof record.documentId === 'string' && record.documentId.trim() &&
typeof record.versionId === 'string' && record.versionId.trim()) {
return { status: 'completed_recorded', documentId: record.documentId, versionId: record.versionId };
}
throw new Doc0InspectionUnavailableError();
}
}