From c5daf15f9ff6518cdaffd4578996ec13906ea15e Mon Sep 17 00:00:00 2001 From: Alexey Grigorev Date: Sun, 22 Nov 2026 18:40:14 +0100 Subject: [PATCH 1/9] Hold knowledge edits until full authored-content validation passes --- backend/src/auth/knowledgePublisher.ts | 19 +++- backend/src/docs/contentApi.ts | 2 + backend/src/docs/knowledgeStore.ts | 5 ++ backend/src/docs/knowledgeValidation.ts | 88 +++++++++++++++++++ backend/tests/docs-content-api.test.ts | 2 +- backend/tests/docs-knowledge-store.test.ts | 2 +- backend/tests/helpers/knowledge.ts | 2 +- .../tests/knowledge-publisher-auth.test.ts | 16 ++++ backend/tests/knowledge-validation.test.ts | 70 +++++++++++++++ 9 files changed, 199 insertions(+), 7 deletions(-) create mode 100644 backend/src/docs/knowledgeValidation.ts create mode 100644 backend/tests/knowledge-validation.test.ts diff --git a/backend/src/auth/knowledgePublisher.ts b/backend/src/auth/knowledgePublisher.ts index d1e9acb97..6bd2c5514 100644 --- a/backend/src/auth/knowledgePublisher.ts +++ b/backend/src/auth/knowledgePublisher.ts @@ -1,3 +1,4 @@ +import { recordValidation, validationCandidate, withValidatedKnowledgePublisher } from '../docs/knowledgeValidation'; /** * The knowledge repository's GitHub Actions publisher, authenticated by the * workflow's own GitHub OIDC token. Nothing is stored: GitHub signs a @@ -33,7 +34,7 @@ const CLOCK_SKEW_SECONDS = 60; type Jwk = JsonWebKey & { kid?: string; alg?: string; use?: string }; export interface GitHubOidcClaims { iss: string; aud: string | string[]; exp: number; nbf?: number; iat?: number; - repository: string; ref: string; sha: string; workflow_ref: string; event_name: string; + repository: string; ref: string; sha: string; workflow_ref: string; event_name: string; run_id?: string; } let jwksCache: { expiresAt: number; keys: Jwk[] } | null = null; @@ -101,7 +102,7 @@ export async function verifyPublisherToken(token: string, now = Date.now()): Pro if (claims.iss !== GITHUB_OIDC_ISSUER || !audience.includes(KNOWLEDGE_PUBLISHER_AUDIENCE)) throw new Error('Invalid token claims'); if (typeof claims.exp !== 'number' || claims.exp <= seconds - CLOCK_SKEW_SECONDS) throw new Error('Expired token'); if (claims.nbf !== undefined && claims.nbf > seconds + CLOCK_SKEW_SECONDS) throw new Error('Token not yet valid'); - if (claims.repository !== policy.repository || claims.ref !== policy.ref || claims.workflow_ref !== policy.workflowRef) { + if (claims.repository !== policy.repository || claims.ref !== policy.ref || ![policy.workflowRef, policy.workflowRef.replace('/validate.yml@', '/validate-candidate.yml@')].includes(claims.workflow_ref)) { throw new Error('Token is not from the knowledge publish workflow'); } if (!ALLOWED_EVENTS.has(claims.event_name) || !/^[0-9a-f]{40}$/.test(claims.sha)) throw new Error('Invalid token claims'); @@ -127,7 +128,17 @@ export async function handleKnowledgePublisher( } const method = (event.httpMethod || 'GET').toUpperCase(); const path = event.path || '/'; - if (method === 'POST' && path === '/api/templates/sync') return syncTemplates(client, claims); + if (/^\/knowledge\/validation\/[a-f0-9]{64}$/.test(path)) { + const id = path.split('/').pop()!; + if (method === 'GET') return response(200, await validationCandidate(docsKnowledgeStore(), id)); + if (method === 'POST') { + const body = JSON.parse(event.body || '{}'); + await recordValidation(docsKnowledgeStore(), id, { status: body.status, runUrl: `https://github.com/${claims.repository}/actions/runs/${claims.run_id}` }); + return response(200, { recorded: body.status }); + } + } + if (claims.workflow_ref.includes('/validate-candidate.yml@') && !(method === 'GET' && ['/knowledge/download', '/knowledge/version'].includes(path))) return response(403, { error: 'Candidate validator may only read immutable versions and record validation results' }); + if (method === 'POST' && path === '/api/templates/sync') return withValidatedKnowledgePublisher(() => syncTemplates(client, claims)); if (method === 'POST' && path === '/knowledge/mirror-heartbeat') { const heartbeat = parseMirrorHeartbeat(event.body); if (!heartbeat) return response(400, { error: 'outcome must be success or failure' }); @@ -138,7 +149,7 @@ export async function handleKnowledgePublisher( || (method === 'POST' && path === '/knowledge/publish'); if (!allowed) return response(403, { error: 'Knowledge publisher may only read the manifest, file history and versions, publish knowledge files, report mirror heartbeats and sync workflow templates' }); const repo = claims.repository.split('/')[1]; - const result = await handleDocsRoutes(event, `git:${repo}@${claims.sha.slice(0, 12)}`, `Publish ${repo} ${claims.sha}`, undefined, client); + const result = await withValidatedKnowledgePublisher(() => handleDocsRoutes(event, `git:${repo}@${claims.sha.slice(0, 12)}`, `Publish ${repo} ${claims.sha}`, undefined, client)); return result || response(404, { error: 'Not found' }); } diff --git a/backend/src/docs/contentApi.ts b/backend/src/docs/contentApi.ts index 0ace83540..a886d1726 100644 --- a/backend/src/docs/contentApi.ts +++ b/backend/src/docs/contentApi.ts @@ -1,3 +1,4 @@ +import { KnowledgeValidationError } from './knowledgeValidation'; import { authoredContentIssues, blockingAuthoredContentIssues } from './authoredContent'; import { templateParser } from './templatePlaceholders'; import { dump as dumpYaml } from 'js-yaml'; @@ -470,6 +471,7 @@ export async function handleDocsRoutes( } if (err instanceof KnowledgeVersionNotFound) return jsonResponse(404,{error:err.message}); if (err instanceof RevisionConflict) return jsonResponse(409, { error: err.message }); + if (err instanceof KnowledgeValidationError) return jsonResponse(err.status === 'pending' ? 422 : err.status === 'unavailable' ? 503 : 400, { error: err.message, validation: { id: err.id, status: err.status, url: err.runUrl } }); if (err instanceof KnowledgeError) return jsonResponse(400, { error: err.message }); recordRequestError(err); return jsonResponse(500, { error: 'Internal server error' }); diff --git a/backend/src/docs/knowledgeStore.ts b/backend/src/docs/knowledgeStore.ts index a715bc62c..bdd485bee 100644 --- a/backend/src/docs/knowledgeStore.ts +++ b/backend/src/docs/knowledgeStore.ts @@ -1,3 +1,4 @@ +import { requireKnowledgeValidation } from './knowledgeValidation'; import { blockingAuthoredContentIssues } from './authoredContent'; import { templateParser } from './templatePlaceholders'; /** Private S3 knowledge: immutable blobs/manifests and one conditional publication pointer. */ @@ -33,6 +34,7 @@ export interface Publication { } export interface KnowledgeConfig { bucket?: string; cacheDir?: string; offline?: boolean; signer?: typeof getSignedUrl; client?: Pick; + validate?: typeof requireKnowledgeValidation; } export interface Mutation { path: string; bytes?: Uint8Array|string; sourcePath?: string; restoreRevision?: string; absent?: boolean; } /** Normalize a repo-relative path; reject traversal and absolute paths. */ @@ -157,8 +159,10 @@ export class KnowledgeStore { private hydrated=false; private localOffline:boolean|undefined; private signer:typeof getSignedUrl; + private readonly validate: typeof requireKnowledgeValidation; constructor(config:KnowledgeConfig={}) { this.signer=config.signer||getSignedUrl; + this.validate=config.validate || requireKnowledgeValidation; this.localOffline=config.offline; this.bucket=config.bucket||process.env.KNOWLEDGE_BUCKET||''; this.client=config.client||new S3Client({}); @@ -343,6 +347,7 @@ export class KnowledgeStore { if (issues.length) throw new KnowledgeError(`${path}: ${issues.map(issue => issue.message).join(' ')}`); } } + await this.validate(this, previous, mutations, actor); const entries={...previous.entries};const changes:KnowledgeChange[]=[]; for(const mutation of mutations) { const path=normalizeRepoPath(mutation.path); diff --git a/backend/src/docs/knowledgeValidation.ts b/backend/src/docs/knowledgeValidation.ts new file mode 100644 index 000000000..ca2ea9e1f --- /dev/null +++ b/backend/src/docs/knowledgeValidation.ts @@ -0,0 +1,88 @@ +/** Full repository gates run on an immutable, private candidate before activation. + * The ordinary save fails visibly while validation is pending; retrying the same + * save consumes the receipt. Only the verified main-branch publisher can write + * receipts or bypass validation (its own publication already passed the gates). + */ +import { AsyncLocalStorage } from 'node:async_hooks'; +import { createHash } from 'node:crypto'; +import { PutObjectCommand } from '@aws-sdk/client-s3'; +import { readRuntimeSecret } from '../secrets/reader'; +import type { KnowledgeStore, Mutation, Publication } from './knowledgeStore'; + +const publisher = new AsyncLocalStorage(); +export const withValidatedKnowledgePublisher = (action: () => Promise): Promise => publisher.run(true, action); +const hash = (value: string | Uint8Array) => createHash('sha256').update(value).digest('hex'); +const prefix = (id: string) => { + if (!/^[a-f0-9]{64}$/.test(id)) throw new Error('Invalid knowledge validation id'); + return `jobs/knowledge-validation/${id}`; +}; +export interface Candidate { + id: string; baseRevision: string; actor: string; + entries: Publication['entries']; + mutations: { path: string; base64?: string }[]; +} +export interface ValidationReceipt { status: 'passed' | 'failed'; runUrl: string; } +export class KnowledgeValidationError extends Error { + constructor(readonly id: string, readonly status: 'pending' | 'failed' | 'unavailable', readonly runUrl: string) { + super(status === 'unavailable' ? `Could not start full knowledge validation. The active document is unchanged and your draft is preserved. Retry later; validation service: ${runUrl}.` : status === 'pending' + ? `Knowledge edit is pending the full authored-content gates and has not been saved. Validation: ${runUrl}. Retry the same save after validation finishes.` + : `Knowledge edit rejected: the full authored-content gates failed. The active document is unchanged. Fix the findings at ${runUrl} and save again.`); + } +} +async function optionalJson(store: KnowledgeStore, key: string): Promise { + try { return (await store.json(key)).value; } + catch (error) { if (['NoSuchKey', 'NotFound'].includes((error as Error).name)) return undefined; throw error; } +} +export async function validationCandidate(store: KnowledgeStore, id: string): Promise { + return (await store.json(`${prefix(id)}/request.json`)).value; +} +/** Called only by the verified GitHub OIDC publisher, never from docs dispatch. */ +export async function recordValidation(store: KnowledgeStore, id: string, receipt: ValidationReceipt): Promise { + await validationCandidate(store, id); + const repository = process.env.KNOWLEDGE_PUBLISHER_REPOSITORY || 'DataTalksClub/dataops-knowledge'; + if (!['passed', 'failed'].includes(receipt.status) || !receipt.runUrl.startsWith(`https://github.com/${repository}/actions/runs/`) || !/\/runs\/[0-9]+$/.test(receipt.runUrl)) { + throw new Error('Invalid validation receipt'); + } + await store.client.send(new PutObjectCommand({ Bucket: store.bucket, Key: `${prefix(id)}/result.json`, Body: JSON.stringify(receipt), ContentType: 'application/json' })); +} +export async function dispatchValidation(id: string): Promise { + const token = await readRuntimeSecret('dataops-v1.knowledge.github-token'); + const response = await fetch('https://api.github.com/repos/DataTalksClub/dataops-knowledge/actions/workflows/validate-candidate.yml/dispatches', { + method: 'POST', headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'content-type': 'application/json' }, + body: JSON.stringify({ ref: 'main', inputs: { candidate: id } }), signal: AbortSignal.timeout(10_000), + }); + // Never echo provider bodies: they can contain request data or credentials. + if (!response.ok) throw new Error(`Knowledge validation workflow dispatch failed (HTTP ${response.status}); the active knowledge is unchanged`); +} +export async function requireKnowledgeValidation( + store: KnowledgeStore, previous: Publication, mutations: Mutation[], actor: string, + dispatch: (id: string) => Promise = dispatchValidation, +): Promise { + if (publisher.getStore()) return; + const resolved: Candidate['mutations'] = []; + for (const mutation of mutations) { + let bytes: string | Uint8Array | undefined = mutation.bytes; + if (bytes === undefined && mutation.sourcePath) bytes = await store.blobBytes(previous.entries[mutation.sourcePath]?.sha || ''); + if (bytes === undefined && mutation.restoreRevision) bytes = await store.versionBytes(mutation.path, mutation.restoreRevision); + resolved.push({ path: mutation.path, ...(bytes !== undefined ? { base64: Buffer.from(bytes).toString('base64') } : {}) }); + if (mutation.sourcePath) resolved.push({ path: mutation.sourcePath }); + } + // Include operation order: a batch may write a path more than once. + const payload = { baseRevision: previous.revision, actor, entries: previous.entries, mutations: resolved }; + const id = hash(JSON.stringify(payload)); + const receipt = await optionalJson(store, `${prefix(id)}/result.json`); + if (receipt?.status === 'passed') return; + if (receipt?.status === 'failed') throw new KnowledgeValidationError(id, 'failed', receipt.runUrl); + const runUrl = `https://github.com/DataTalksClub/dataops-knowledge/actions?query=${encodeURIComponent(id)}`; + const queued = await optionalJson<{ dispatched: boolean }>(store, `${prefix(id)}/dispatch.json`); + if (!queued?.dispatched) { + await store.client.send(new PutObjectCommand({ Bucket: store.bucket, Key: `${prefix(id)}/request.json`, Body: JSON.stringify({ id, ...payload }), ContentType: 'application/json' })); + try { await dispatch(id); } + catch (error) { + console.error('Knowledge validation dispatch failed', error instanceof Error ? error.message : 'Unknown provider failure'); + throw new KnowledgeValidationError(id, 'unavailable', runUrl); + } + await store.client.send(new PutObjectCommand({ Bucket: store.bucket, Key: `${prefix(id)}/dispatch.json`, Body: JSON.stringify({ dispatched: true }), ContentType: 'application/json' })); + } + throw new KnowledgeValidationError(id, 'pending', runUrl); +} diff --git a/backend/tests/docs-content-api.test.ts b/backend/tests/docs-content-api.test.ts index a688a7822..83c4a3af1 100644 --- a/backend/tests/docs-content-api.test.ts +++ b/backend/tests/docs-content-api.test.ts @@ -553,7 +553,7 @@ describe('docs search ranking, snippets and the per-publication index',()=>{ }); it('reuses one index across requests for a publication and rebuilds after a new one',async()=>{ const fixture=syntheticKnowledge(files,dir); - const freshStore=()=>new KnowledgeStore({bucket:'test-knowledge',client:fixture.s3 as any,cacheDir:dir,offline:false}); + const freshStore=()=>new KnowledgeStore({bucket:'test-knowledge',client:fixture.s3 as any,cacheDir:dir,offline:false,validate:async()=>{}}); configureDocsRuntime(freshStore()); assert.equal((await call(ev('GET','/search',{query:{q:'sponsor'}}))).body.results.length,2); // A second request (new runtime, new store) on the same publication must not re-read the corpus. diff --git a/backend/tests/docs-knowledge-store.test.ts b/backend/tests/docs-knowledge-store.test.ts index 1b1976aab..933db5cd2 100644 --- a/backend/tests/docs-knowledge-store.test.ts +++ b/backend/tests/docs-knowledge-store.test.ts @@ -46,7 +46,7 @@ describe('immutable S3 knowledge publications',()=>{ const dir=mkdtempSync(resolve('../.tmp/knowledge-test-')); try { const {store,s3,publication}=syntheticKnowledge({'content/a.md':'old','definitions/model.csv':'a,b\n1,2'},dir); - const second=new KnowledgeStore({bucket:store.bucket,client:s3 as any,cacheDir:dir});await second.pin(); + const second=new KnowledgeStore({bucket:store.bucket,client:s3 as any,cacheDir:dir,validate:async()=>{}});await second.pin(); const saved=await store.publish([{path:'content/a.md',bytes:'new'}],publication.revision,'authenticated-actor','Edit'); await assert.rejects(()=>second.publish([{path:'content/a.md',bytes:'stale'}],publication.revision,'other','Edit'),RevisionConflict); assert.equal(await second.readFile('content/a.md'),'old');assert.equal(await store.readFile('content/a.md'),'new'); diff --git a/backend/tests/helpers/knowledge.ts b/backend/tests/helpers/knowledge.ts index e3d5cf5b8..d6ee29e70 100644 --- a/backend/tests/helpers/knowledge.ts +++ b/backend/tests/helpers/knowledge.ts @@ -35,5 +35,5 @@ export class MemoryS3 { } } export function syntheticKnowledge(files:Record,cacheDir?:string,signer?:KnowledgeConfig['signer']) { - const s3=new MemoryS3();const publication=s3.seed(files);const store=new KnowledgeStore({bucket:'test-knowledge',client:s3 as any,cacheDir,offline:false,signer});return{s3,store,publication}; + const s3=new MemoryS3();const publication=s3.seed(files);const store=new KnowledgeStore({bucket:'test-knowledge',client:s3 as any,cacheDir,offline:false,signer,validate:async()=>{}});return{s3,store,publication}; } diff --git a/backend/tests/knowledge-publisher-auth.test.ts b/backend/tests/knowledge-publisher-auth.test.ts index 0807d1431..236d8fdea 100644 --- a/backend/tests/knowledge-publisher-auth.test.ts +++ b/backend/tests/knowledge-publisher-auth.test.ts @@ -261,6 +261,22 @@ describe('GitHub Actions OIDC knowledge publisher', () => { } }); + it('limits candidate workflow credentials to immutable reads and receipts', async () => { + const credential = token(claims({ workflow_ref: `${REPO}/.github/workflows/validate-candidate.yml@refs/heads/main`, event_name: 'workflow_dispatch', run_id: '123' })); + for (const path of ['/knowledge/publish', '/knowledge/mirror-heartbeat', '/api/templates/sync']) { + const denied = await request('POST', path, credential); + assert.equal(denied.statusCode, 403, path); + } + const id = 'c'.repeat(64); + s3.objects.set(`test-knowledge/jobs/knowledge-validation/${id}/request.json`, Buffer.from(JSON.stringify({ id }))); + const read = await request('GET', `/knowledge/validation/${id}`, credential); + assert.equal(read.statusCode, 200); + const recorded = await request('POST', `/knowledge/validation/${id}`, credential, { status: 'passed', runUrl: 'https://untrusted.example/' }); + assert.equal(recorded.statusCode, 200); + const receipt = JSON.parse(s3.objects.get(`test-knowledge/jobs/knowledge-validation/${id}/result.json`)!.toString()); + assert.equal(receipt.runUrl, `https://github.com/${REPO}/actions/runs/123`); + }); + it('is disabled when the deployment names no repository', async () => { delete process.env.KNOWLEDGE_PUBLISHER_REPOSITORY; try { diff --git a/backend/tests/knowledge-validation.test.ts b/backend/tests/knowledge-validation.test.ts new file mode 100644 index 000000000..dfa855b72 --- /dev/null +++ b/backend/tests/knowledge-validation.test.ts @@ -0,0 +1,70 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { KnowledgeStore } from '../src/docs/knowledgeStore'; +import { KnowledgeValidationError, recordValidation, requireKnowledgeValidation, validationCandidate, withValidatedKnowledgePublisher } from '../src/docs/knowledgeValidation'; +import { syntheticKnowledge } from './helpers/knowledge'; + +const url = 'https://github.com/DataTalksClub/dataops-knowledge/actions/runs/123'; +const change = [{ path: 'content/example.md', bytes: 'New content' }]; +test('full gate holds activation, deduplicates retries, binds receipts to exact bytes, base and actor', async () => { + const { s3, store, publication } = syntheticKnowledge({ 'content/example.md': 'Original' }); + const dispatched: string[] = []; + const dispatch = async (id: string) => { dispatched.push(id); }; + let id = ''; + for (let retry = 0; retry < 2; retry++) { + await assert.rejects(() => requireKnowledgeValidation(store, publication, change, 'editor', dispatch), (error: unknown) => { + assert.ok(error instanceof KnowledgeValidationError); + assert.equal(error.status, 'pending'); + id = error.id; + return true; + }); + } + assert.equal(dispatched.length, 1); + assert.equal(JSON.parse(s3.objects.get(`${store.bucket}/active.json`)!.toString()).revision, publication.revision); + assert.equal((await validationCandidate(store, id)).mutations[0].base64, Buffer.from('New content').toString('base64')); + await recordValidation(store, id, { status: 'passed', runUrl: url }); + await requireKnowledgeValidation(store, publication, change, 'editor', dispatch); + for (const [base, mutations, actor] of [ + [publication, [{ ...change[0], bytes: 'Different' }], 'editor'], + [{ ...publication, revision: 'another' }, change, 'editor'], + [publication, change, 'another-editor'], + ] as const) { + await assert.rejects(() => requireKnowledgeValidation(store, base, [...mutations], actor, dispatch), KnowledgeValidationError); + } +}); +test('failed gates stay rejected and dispatch errors stay loud and retryable', async () => { + const { store, publication } = syntheticKnowledge({ 'content/example.md': 'Original' }); + await assert.rejects(() => requireKnowledgeValidation(store, publication, change, 'editor', async () => { throw new Error('HTTP 403'); }), /Could not start full knowledge validation/); + let id = ''; + await assert.rejects(() => requireKnowledgeValidation(store, publication, change, 'editor', async value => { id = value; }), KnowledgeValidationError); + await recordValidation(store, id, { status: 'failed', runUrl: url }); + await assert.rejects(() => requireKnowledgeValidation(store, publication, change, 'editor'), (error: unknown) => { + assert.ok(error instanceof KnowledgeValidationError); + assert.equal(error.status, 'failed'); + assert.match(error.message, /rejected/); + return true; + }); +}); +test('store enforces the full gate and publisher trust is scoped to its async request', async () => { + const { s3, publication } = syntheticKnowledge({ 'asset.bin': 'Original' }); + const store = new KnowledgeStore({ bucket: 'test-knowledge', client: s3, offline: false, validate: (target, prior, mutations, actor) => requireKnowledgeValidation(target, prior, mutations, actor, async () => {}) }); + const mutation = [{ path: 'asset.bin', bytes: 'Changed' }]; + await assert.rejects(() => store.publish(mutation, publication.revision, 'editor', 'Edit'), KnowledgeValidationError); + const saved = await withValidatedKnowledgePublisher(() => store.publish(mutation, publication.revision, 'publisher', 'Publish tested commit')); + assert.notEqual(saved.revision, publication.revision); + await assert.rejects(() => store.publish(mutation, saved.revision, 'editor', 'Edit'), KnowledgeValidationError); +}); +test('rename with replacement and restore candidates carry exact effective bytes', async () => { + const { store, publication } = syntheticKnowledge({ 'content/old.md': 'Original' }); + let id = ''; + const mutations = [{ path: 'content/new.md', sourcePath: 'content/old.md', bytes: 'Replacement' }, { path: 'content/restored.md', restoreRevision: publication.revision }]; + // Restore an existing historical path, including a rename in the same batch. + mutations[1].path = 'content/old.md'; + await assert.rejects(() => requireKnowledgeValidation(store, publication, mutations, 'editor', async value => { id = value; }), KnowledgeValidationError); + const candidate = await validationCandidate(store, id); + assert.deepEqual(candidate.mutations, [ + { path: 'content/new.md', base64: Buffer.from('Replacement').toString('base64') }, + { path: 'content/old.md' }, + { path: 'content/old.md', base64: Buffer.from('Original').toString('base64') }, + ]); +}); From 3294e2bdc636c07d5d1530b85707193161d0aa56 Mon Sep 17 00:00:00 2001 From: Alexey Grigorev Date: Sun, 22 Nov 2026 18:42:30 +0100 Subject: [PATCH 2/9] Isolate browser fixtures from the remote knowledge gate --- backend/scripts/test-server.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/backend/scripts/test-server.ts b/backend/scripts/test-server.ts index 0fa59f482..6bbdc967f 100644 --- a/backend/scripts/test-server.ts +++ b/backend/scripts/test-server.ts @@ -119,8 +119,8 @@ function configureOfflineDocsStore(): void { } collect(source); const s3=new MemoryS3();s3.seed(files); - const store=new KnowledgeStore({bucket:'test-knowledge',client:s3 as any,cacheDir:source+'/s3-cache',offline:false}); - configureOperatingModelStoreForTests(()=>new KnowledgeStore({bucket:'test-knowledge',client:s3 as any,cacheDir:source+'/s3-cache',offline:false})); + const store=new KnowledgeStore({bucket:'test-knowledge',client:s3 as any,cacheDir:source+'/s3-cache',offline:false,validate:async()=>{}}); + configureOperatingModelStoreForTests(()=>new KnowledgeStore({bucket:'test-knowledge',client:s3 as any,cacheDir:source+'/s3-cache',offline:false,validate:async()=>{}})); configureDocsRuntime(store); configurePortalStore(store); } From a3d1f59ea474ecb34fb8582b4631f7b6412986e7 Mon Sep 17 00:00:00 2001 From: Alexey Grigorev Date: Sun, 22 Nov 2026 18:46:38 +0100 Subject: [PATCH 3/9] Keep portal authorization fixtures independent of remote validation --- backend/tests/docs-portal.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backend/tests/docs-portal.test.ts b/backend/tests/docs-portal.test.ts index 68649a602..086d5ba7d 100644 --- a/backend/tests/docs-portal.test.ts +++ b/backend/tests/docs-portal.test.ts @@ -79,7 +79,7 @@ describe('portal - single-origin auth + frontend + docs wiring', () => { 'content/00-start-here/operating-model/assets/chart.png': 'CHART', '_docs/operating-model/weekly-roadmap.csv': 'week,title\nW01,Foundation\n', }); - const store = new KnowledgeStore({bucket:'test-knowledge',client:portalStorage as any,cacheDir,signer:async()=> 'https://example.invalid/synthetic-download'}); + const store = new KnowledgeStore({bucket:'test-knowledge',client:portalStorage as any,cacheDir,validate:async()=>{},signer:async()=> 'https://example.invalid/synthetic-download'}); configureDocsRuntime(store); configurePortalStore(store); }); From cf2553d8f8d4fb66eb5fbb7b587d14f5a2cba63b Mon Sep 17 00:00:00 2001 From: Alexey Grigorev Date: Sun, 22 Nov 2026 18:48:41 +0100 Subject: [PATCH 4/9] Validate the final bytes of ordered knowledge batches --- backend/src/docs/knowledgeValidation.ts | 21 ++++++++++++++++----- backend/tests/knowledge-validation.test.ts | 16 +++++++++++++++- 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/backend/src/docs/knowledgeValidation.ts b/backend/src/docs/knowledgeValidation.ts index ca2ea9e1f..6b4dc3f59 100644 --- a/backend/src/docs/knowledgeValidation.ts +++ b/backend/src/docs/knowledgeValidation.ts @@ -59,15 +59,26 @@ export async function requireKnowledgeValidation( dispatch: (id: string) => Promise = dispatchValidation, ): Promise { if (publisher.getStore()) return; - const resolved: Candidate['mutations'] = []; + // Resolve operations in their actual publication order, then canonicalize + // the final writes. A rename can copy a source edited earlier in the batch. + const effective = new Map(); + const read = async (path: string): Promise => { + if (effective.has(path)) { + const base64 = effective.get(path); + if (base64 === undefined) throw new Error('Knowledge rename source was deleted earlier in the batch'); + return Buffer.from(base64, 'base64'); + } + return store.blobBytes(previous.entries[path]?.sha || ''); + }; for (const mutation of mutations) { let bytes: string | Uint8Array | undefined = mutation.bytes; - if (bytes === undefined && mutation.sourcePath) bytes = await store.blobBytes(previous.entries[mutation.sourcePath]?.sha || ''); + if (bytes === undefined && mutation.sourcePath) bytes = await read(mutation.sourcePath); if (bytes === undefined && mutation.restoreRevision) bytes = await store.versionBytes(mutation.path, mutation.restoreRevision); - resolved.push({ path: mutation.path, ...(bytes !== undefined ? { base64: Buffer.from(bytes).toString('base64') } : {}) }); - if (mutation.sourcePath) resolved.push({ path: mutation.sourcePath }); + effective.set(mutation.path, bytes === undefined ? undefined : Buffer.from(bytes).toString('base64')); + if (mutation.sourcePath) effective.set(mutation.sourcePath, undefined); } - // Include operation order: a batch may write a path more than once. + const resolved = [...effective].sort(([a], [b]) => a.localeCompare(b)) + .map(([path, base64]) => ({ path, ...(base64 !== undefined ? { base64 } : {}) })); const payload = { baseRevision: previous.revision, actor, entries: previous.entries, mutations: resolved }; const id = hash(JSON.stringify(payload)); const receipt = await optionalJson(store, `${prefix(id)}/result.json`); diff --git a/backend/tests/knowledge-validation.test.ts b/backend/tests/knowledge-validation.test.ts index dfa855b72..c5657f49e 100644 --- a/backend/tests/knowledge-validation.test.ts +++ b/backend/tests/knowledge-validation.test.ts @@ -64,7 +64,21 @@ test('rename with replacement and restore candidates carry exact effective bytes const candidate = await validationCandidate(store, id); assert.deepEqual(candidate.mutations, [ { path: 'content/new.md', base64: Buffer.from('Replacement').toString('base64') }, - { path: 'content/old.md' }, { path: 'content/old.md', base64: Buffer.from('Original').toString('base64') }, ]); }); + +test('candidate matches a rename of an earlier edit and canonicalizes independent write order', async () => { + const { store, publication } = syntheticKnowledge({ 'content/a.md': 'Old', 'content/z.md': 'Z' }); + let id = ''; + const mutations = [{ path: 'content/a.md', bytes: 'New' }, { path: 'content/b.md', sourcePath: 'content/a.md' }]; + await assert.rejects(() => requireKnowledgeValidation(store, publication, mutations, 'editor', async value => { id = value; }), KnowledgeValidationError); + assert.deepEqual((await validationCandidate(store, id)).mutations, [ + { path: 'content/a.md' }, { path: 'content/b.md', base64: Buffer.from('New').toString('base64') }, + ]); + let first = ''; + const writes = [{ path: 'content/a.md', bytes: 'A' }, { path: 'content/z.md', bytes: 'Z' }]; + await assert.rejects(() => requireKnowledgeValidation(store, publication, writes, 'editor', async value => { first = value; }), KnowledgeValidationError); + await recordValidation(store, first, { status: 'passed', runUrl: url }); + await requireKnowledgeValidation(store, publication, [...writes].reverse(), 'editor', async () => { throw new Error('Should reuse exact final state'); }); +}); From 57192047c4a7e41a2bb3fb6ff0040a1d811191eb Mon Sep 17 00:00:00 2001 From: Alexey Grigorev Date: Sun, 22 Nov 2026 18:55:51 +0100 Subject: [PATCH 5/9] Verify pending and approved decisions through the real docs save route --- backend/tests/knowledge-validation.test.ts | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/backend/tests/knowledge-validation.test.ts b/backend/tests/knowledge-validation.test.ts index c5657f49e..e3d200d10 100644 --- a/backend/tests/knowledge-validation.test.ts +++ b/backend/tests/knowledge-validation.test.ts @@ -82,3 +82,29 @@ test('candidate matches a rename of an earlier edit and canonicalizes independen await recordValidation(store, first, { status: 'passed', runUrl: url }); await requireKnowledgeValidation(store, publication, [...writes].reverse(), 'editor', async () => { throw new Error('Should reuse exact final state'); }); }); + +test('the actual docs save route exposes pending, failed and accepted validation decisions', async () => { + const { configureDocsRuntime, resetDocsRuntime, handleDocsRoutes } = await import('../src/docs/contentApi'); + const content = '---\nid: reference.example\ndoc_type: reference\nstatus: proposed\nconfidentiality: internal\n---\n# Example\n\n## References\n- Service documentation\n'; + const { s3, publication } = syntheticKnowledge({ 'content/example.md': content }); + const store = new KnowledgeStore({ bucket: 'test-knowledge', client: s3, offline: false, validate: (target, prior, mutations, actor) => requireKnowledgeValidation(target, prior, mutations, actor, async () => {}) }); + configureDocsRuntime(store); + const event = { httpMethod: 'PUT', path: '/docs', headers: {}, queryStringParameters: { path: 'content/example.md' }, body: JSON.stringify({ content: content + '\nChanged.\n', expectedRevision: publication.revision }) }; + try { + const pending = await handleDocsRoutes(event, 'editor'); + assert.equal(pending?.statusCode, 422, pending?.body); + const decision = JSON.parse(pending!.body).validation; + assert.equal(decision.status, 'pending'); + assert.match(JSON.parse(pending!.body).error, /has not been saved/); + assert.equal((await store.pin()).revision, publication.revision); + await recordValidation(store, decision.id, { status: 'failed', runUrl: url }); + const rejected = await handleDocsRoutes(event, 'editor'); + assert.equal(rejected?.statusCode, 400); + assert.equal((await store.pin()).revision, publication.revision); + await recordValidation(store, decision.id, { status: 'passed', runUrl: url }); + const accepted = await handleDocsRoutes(event, 'editor'); + assert.equal(accepted?.statusCode, 200, accepted?.body); + assert.notEqual((await store.pin()).revision, publication.revision); + assert.equal(await store.readFile('content/example.md'), content + '\nChanged.\n'); + } finally { resetDocsRuntime(); } +}); From d671c1fe1fb2f8dcfc244cd3b84b134d60c1f25a Mon Sep 17 00:00:00 2001 From: Alexey Grigorev Date: Sun, 22 Nov 2026 19:01:11 +0100 Subject: [PATCH 6/9] Keep marked SOP steps in a single numbered Document list --- .../src/surfaces/document-editor/block-model.js | 6 +++++- frontend/test/document-editor-blocks.test.mjs | 15 +++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/frontend/src/surfaces/document-editor/block-model.js b/frontend/src/surfaces/document-editor/block-model.js index 37e76c41f..4e6aa154b 100644 --- a/frontend/src/surfaces/document-editor/block-model.js +++ b/frontend/src/surfaces/document-editor/block-model.js @@ -155,7 +155,11 @@ export function parseMarkdownBlocks(markdown) { if (/^\s*\d+\.\s+/.test(startLine)) { const buf = [startLine]; i++; - while (i < lines.length && lines[i].trim() && /^\s*\d+\.\s+/.test(lines[i])) { + while (i < lines.length) { + // Step markers are non-content, just like comments between blocks. + // Keep adjacent SOP steps in one ordered list when markers wrap them. + if (/^\s*\s*$/.test(lines[i])) { i++; continue; } + if (!lines[i].trim() || !/^\s*\d+\.\s+/.test(lines[i])) break; buf.push(lines[i]); i++; } diff --git a/frontend/test/document-editor-blocks.test.mjs b/frontend/test/document-editor-blocks.test.mjs index d6cbf7f93..d6ad18474 100644 --- a/frontend/test/document-editor-blocks.test.mjs +++ b/frontend/test/document-editor-blocks.test.mjs @@ -187,3 +187,18 @@ describe("block keyboard model", () => { assert.equal(serializeBlocksToMarkdown(list), "![Shot](a.png)\n\nhttps://www.youtube.com/watch?v=abc\n\nhttps://example.com"); }); }); + + +test("SOP step markers preserve one sequential numbered list in Document view", () => { + const marked = [ + "", "1. First action.", "", + "", "2. Second action.", "", + "## Validation", "Verify the result.", + ].join("\n"); + const blocks = parseMarkdownBlocks(marked); + assert.equal(blocks[0].type, "numbered"); + assert.equal(blocks[0].raw, "1. First action.\n2. Second action."); + assert.equal(blocks[1].raw, "## Validation"); + const code = parseMarkdownBlocks("```html\n\n```"); + assert.ok(code[0].raw.includes("")); +}); From 432e6b1116dab23a640b0d3b3c37dfea28f73218 Mon Sep 17 00:00:00 2001 From: Alexey Grigorev Date: Sun, 22 Nov 2026 19:25:55 +0100 Subject: [PATCH 7/9] Preflight Template-derived knowledge before writing the source version --- backend/src/db/templates.ts | 19 +++++-- backend/src/docs/contentApi.ts | 7 +++ backend/src/docs/knowledgeStore.ts | 6 ++- backend/src/routes/templates.ts | 11 +++-- backend/tests/template-runtime-edits.test.ts | 52 ++++++++++++++++++++ 5 files changed, 87 insertions(+), 8 deletions(-) diff --git a/backend/src/db/templates.ts b/backend/src/db/templates.ts index b6a74a689..dbc4681f1 100644 --- a/backend/src/db/templates.ts +++ b/backend/src/db/templates.ts @@ -610,11 +610,14 @@ async function ensureTypeGuard( } } +type BeforeTemplateWrite = (template: Template) => Promise; + /** Claim a `type` and store its template atomically; losers fail closed. */ async function createTemplateWithGuard( client: DynamoDBDocumentClient, fields: Record, type: string, + beforeWrite?: BeforeTemplateWrite, ): Promise