@unson/brainbase-mcp 0.11.0 → 0.13.0

package/contracts/judgment-value-proof/schema.json

@@ -154,7 +154,25 @@
         "entity_id": { "type": "string", "minLength": 1 },
         "application": { "type": "string", "minLength": 1 },
         "layer": { "enum": ["philosophy", "objective", "world_model", "method", "constraint", "other"] },
-        "version": { "type": ["string", "null"] }
+        "version": { "type": ["string", "null"] },
+        "source": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/basis_source" }
+          ]
+        }
+      }
+    },
+    "basis_source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "entity_id", "entity_type"],
+      "properties": {
+        "kind": { "const": "local_graph" },
+        "entity_id": { "type": "string", "minLength": 1 },
+        "entity_type": { "enum": ["person", "org", "project", "decision"] },
+        "version": { "type": ["string", "null"] },
+        "digest": { "type": ["string", "null"] }
       }
     },
     "inheritance_source": {

package/dist/judgment-problem-snapshot-http.d.ts

@@ -0,0 +1,40 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type JudgmentProblemReferenceProvider, type JudgmentProblemSnapshotAccessProvider } from './judgment-problem-snapshot.js';
+type MaybePromise<T> = T | Promise<T>;
+/** Identity resolved by the host after authentication. Request bodies never supply it. */
+export interface TrustedJudgmentProblemSnapshotRequestContext {
+    principal: string;
+    /** A non-empty value means that the host already verified the mutation origin. */
+    verifiedMutationOrigin?: string;
+}
+/**
+ * The host binds the reference resolution (for example the Foundation store
+ * and its own resolvers for authority, resource and deadline) to the trusted
+ * request context. The access provider defaults to the snapshot read policy.
+ */
+export type JudgmentProblemSnapshotProviderFactory = (context: TrustedJudgmentProblemSnapshotRequestContext) => MaybePromise<{
+    referenceProvider: JudgmentProblemReferenceProvider;
+    accessProvider?: JudgmentProblemSnapshotAccessProvider;
+}>;
+export interface JudgmentProblemSnapshotHttpOptions {
+    /** Artifact root of the immutable snapshot store. */
+    root: string;
+    providerFactory: JudgmentProblemSnapshotProviderFactory;
+    basePath?: string;
+    bodyLimitBytes?: number;
+    /** Required for hosts that do not attach verifiedMutationOrigin to context. */
+    verifyMutationRequest?: (input: {
+        request: IncomingMessage;
+        context: TrustedJudgmentProblemSnapshotRequestContext;
+    }) => MaybePromise<boolean>;
+}
+/** A composable route handler. `false` means that the request is outside this route. */
+export type JudgmentProblemSnapshotHttpHandler = (request: IncomingMessage, response: ServerResponse, context: TrustedJudgmentProblemSnapshotRequestContext | null) => Promise<boolean>;
+/**
+ * Saves and reads immutable judgment problem snapshots over HTTP. The host
+ * authenticates, binds the principal, and supplies the reference resolution;
+ * this handler never takes identity from the request body.
+ */
+export declare function createJudgmentProblemSnapshotHttpHandler(options: JudgmentProblemSnapshotHttpOptions): JudgmentProblemSnapshotHttpHandler;
+export declare const createJudgmentProblemSnapshotRoute: typeof createJudgmentProblemSnapshotHttpHandler;
+export {};

package/dist/judgment-problem-snapshot-http.js

@@ -0,0 +1,255 @@
+import { JudgmentProblemSnapshotError, loadJudgmentProblemSnapshot, saveJudgmentProblemSnapshot, } from './judgment-problem-snapshot.js';
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const DEFAULT_BASE_PATH = '/judgment-problem-snapshots';
+const snapshotIdPattern = /^sha256:[0-9a-f]{64}$/u;
+class HttpInputError extends Error {
+}
+class BodyLimitError extends Error {
+    constructor() {
+        super('Request body exceeds the configured limit');
+    }
+}
+function requestPath(request) {
+    try {
+        return new URL(request.url ?? '/', 'http://localhost').pathname;
+    }
+    catch {
+        return '/';
+    }
+}
+function headerValue(request, name) {
+    const value = request.headers[name.toLowerCase()];
+    return Array.isArray(value) ? value[0] : value;
+}
+function writeJson(response, statusCode, body, headers = {}) {
+    if (response.headersSent)
+        return;
+    response.statusCode = statusCode;
+    response.setHeader('Content-Type', 'application/json');
+    for (const [name, value] of Object.entries(headers))
+        response.setHeader(name, value);
+    response.end(JSON.stringify(body));
+}
+function writeError(response, statusCode, code, message, headers = {}) {
+    writeJson(response, statusCode, { error: { code, message } }, headers);
+}
+async function readJsonBody(request, limitBytes) {
+    const contentLength = Number(headerValue(request, 'content-length'));
+    if (Number.isFinite(contentLength) && contentLength > limitBytes) {
+        request.resume();
+        throw new BodyLimitError();
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            request.removeListener('data', onData);
+            request.removeListener('end', onEnd);
+            request.removeListener('error', onError);
+            request.removeListener('aborted', onError);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const onData = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buffer.byteLength;
+            if (totalBytes > limitBytes) {
+                request.resume();
+                finish(new BodyLimitError());
+                return;
+            }
+            chunks.push(buffer);
+        };
+        const onEnd = () => finish();
+        const onError = () => finish(new HttpInputError('Request body could not be read'));
+        request.on('data', onData);
+        request.once('end', onEnd);
+        request.once('error', onError);
+        request.once('aborted', onError);
+    });
+    if (chunks.length === 0)
+        throw new HttpInputError('Request body must be a JSON object');
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new HttpInputError('Request body must contain valid JSON');
+    }
+}
+function normalizeBasePath(basePath) {
+    const value = basePath ?? DEFAULT_BASE_PATH;
+    if (!value.startsWith('/'))
+        throw new TypeError('basePath must be an absolute URL path');
+    const normalized = value.replace(/\/+$/u, '');
+    if (normalized.length === 0)
+        throw new TypeError('basePath must not be root');
+    return normalized;
+}
+function matchRoute(pathname, basePath) {
+    const normalized = pathname.replace(/\/+$/u, '') || '/';
+    if (normalized === basePath)
+        return { operation: 'save' };
+    if (!normalized.startsWith(`${basePath}/`))
+        return null;
+    const rest = normalized.slice(basePath.length + 1);
+    if (rest.length === 0 || rest.includes('/'))
+        return { operation: 'unknown' };
+    try {
+        return { operation: 'read', snapshotId: decodeURIComponent(rest) };
+    }
+    catch {
+        return { operation: 'read', snapshotId: null };
+    }
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        && Object.getPrototypeOf(value) === Object.prototype;
+}
+function parseSaveBody(body) {
+    if (!isPlainRecord(body))
+        throw new HttpInputError('Request body must be a JSON object');
+    const keys = Object.keys(body);
+    if (keys.length !== 1 || keys[0] !== 'snapshot')
+        throw new HttpInputError('Request body must contain only snapshot');
+    if (!isPlainRecord(body.snapshot))
+        throw new HttpInputError('snapshot must be a JSON object');
+    return body.snapshot;
+}
+const STATUS_BY_CODE = {
+    invalid_request: 400,
+    missing_reference: 422,
+    not_applicable: 422,
+    unresolved_constraint: 422,
+    unauthorized: 403,
+    not_found: 404,
+    conflict: 409,
+    integrity_mismatch: 409,
+    storage_io_error: 503,
+};
+function snapshotError(error) {
+    if (error instanceof JudgmentProblemSnapshotError) {
+        return { status: STATUS_BY_CODE[error.code] ?? 500, code: error.code, message: error.message };
+    }
+    return { status: 500, code: 'internal_error', message: 'Judgment problem snapshot request failed' };
+}
+function assertContext(context) {
+    if (typeof context.principal !== 'string' || context.principal.trim().length === 0 || context.principal.length > 512) {
+        throw new HttpInputError('Authenticated principal is required');
+    }
+}
+async function mutationVerified(options, request, context) {
+    if (typeof context.verifiedMutationOrigin === 'string' && context.verifiedMutationOrigin.trim().length > 0)
+        return true;
+    if (!options.verifyMutationRequest)
+        return false;
+    try {
+        return (await options.verifyMutationRequest({ request, context })) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Saves and reads immutable judgment problem snapshots over HTTP. The host
+ * authenticates, binds the principal, and supplies the reference resolution;
+ * this handler never takes identity from the request body.
+ */
+export function createJudgmentProblemSnapshotHttpHandler(options) {
+    if (!options || typeof options !== 'object')
+        throw new TypeError('options are required');
+    if (typeof options.root !== 'string' || options.root.trim().length === 0)
+        throw new TypeError('root must be a non-empty path');
+    if (typeof options.providerFactory !== 'function')
+        throw new TypeError('providerFactory is required');
+    const basePath = normalizeBasePath(options.basePath);
+    const bodyLimitBytes = options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES;
+    if (!Number.isInteger(bodyLimitBytes) || bodyLimitBytes <= 0)
+        throw new TypeError('bodyLimitBytes must be a positive integer');
+    return async (request, response, context) => {
+        const route = matchRoute(requestPath(request), basePath);
+        if (!route)
+            return false;
+        if (!context) {
+            writeError(response, 401, 'unauthorized', 'Authenticated judgment problem snapshot context is required');
+            return true;
+        }
+        try {
+            assertContext(context);
+        }
+        catch (error) {
+            writeError(response, 401, 'unauthorized', error instanceof Error ? error.message : 'Authenticated principal is required');
+            return true;
+        }
+        if (route.operation === 'unknown') {
+            writeError(response, 404, 'not_found', 'Judgment problem snapshot route was not found');
+            return true;
+        }
+        const method = (request.method ?? 'GET').toUpperCase();
+        const allowed = route.operation === 'save' ? 'POST' : 'GET';
+        if (method !== allowed) {
+            writeError(response, 405, 'method_not_allowed', 'Method is not allowed for this judgment problem snapshot route', { Allow: allowed });
+            return true;
+        }
+        if (route.operation === 'read') {
+            if (!route.snapshotId || !snapshotIdPattern.test(route.snapshotId)) {
+                writeError(response, 400, 'invalid_request', 'snapshot_id must be sha256:<64 lowercase hex>');
+                return true;
+            }
+            try {
+                const providers = await options.providerFactory(context);
+                const snapshot = await loadJudgmentProblemSnapshot({
+                    root: options.root,
+                    snapshot_id: route.snapshotId,
+                    access: { principal: context.principal },
+                    reference_resolution: 'current',
+                    referenceProvider: providers.referenceProvider,
+                    ...(providers.accessProvider ? { accessProvider: providers.accessProvider } : {}),
+                });
+                writeJson(response, 200, { action: 'read', snapshotId: route.snapshotId, result: snapshot });
+            }
+            catch (error) {
+                const failure = snapshotError(error);
+                writeError(response, failure.status, failure.code, failure.message);
+            }
+            return true;
+        }
+        let snapshot;
+        try {
+            snapshot = parseSaveBody(await readJsonBody(request, bodyLimitBytes));
+        }
+        catch (error) {
+            if (error instanceof BodyLimitError)
+                writeError(response, 413, 'body_too_large', error.message);
+            else
+                writeError(response, 400, 'invalid_request', error instanceof Error ? error.message : 'Request body is invalid');
+            return true;
+        }
+        if (!await mutationVerified(options, request, context)) {
+            writeError(response, 403, 'mutation_origin_unverified', 'Mutation origin could not be verified');
+            return true;
+        }
+        try {
+            const providers = await options.providerFactory(context);
+            const receipt = await saveJudgmentProblemSnapshot({
+                root: options.root,
+                snapshot,
+                access: { principal: context.principal },
+                referenceProvider: providers.referenceProvider,
+                ...(providers.accessProvider ? { accessProvider: providers.accessProvider } : {}),
+            });
+            writeJson(response, receipt.status === 'created' ? 201 : 200, { action: 'save', result: receipt });
+        }
+        catch (error) {
+            const failure = snapshotError(error);
+            writeError(response, failure.status, failure.code, failure.message);
+        }
+        return true;
+    };
+}
+export const createJudgmentProblemSnapshotRoute = createJudgmentProblemSnapshotHttpHandler;

package/dist/judgment-value-proof.d.ts

@@ -14,12 +14,27 @@ export interface JudgmentValueProofArtifactRef {
 }
 /** Which part of the organization's judgment a basis came from. Absent means not recorded. */
 export type JudgmentValueProofBasisLayer = 'philosophy' | 'objective' | 'world_model' | 'method' | 'constraint' | 'other';
+/**
+ * A source that the local Web host can read and open.  This is deliberately
+ * not a URL: the host owns the reader and keeps navigation same-origin.
+ */
+export type JudgmentValueProofBasisSourceKind = 'local_graph';
+export type JudgmentValueProofBasisSourceEntityType = 'person' | 'org' | 'project' | 'decision';
+export interface JudgmentValueProofBasisSource {
+    kind: JudgmentValueProofBasisSourceKind;
+    entity_id: string;
+    entity_type: JudgmentValueProofBasisSourceEntityType;
+    version?: string | null;
+    digest?: string | null;
+}
 export interface JudgmentValueProofBasis {
     entity_id: string;
     application: string;
     layer?: JudgmentValueProofBasisLayer;
     /** Version of the referenced entity used for this judgment. */
     version?: string | null;
+    /** Optional, typed read contract for a source-bearing proof. */
+    source?: JudgmentValueProofBasisSource | null;
 }
 export interface JudgmentValueProofInheritanceSource {
     kind: 'judgment' | 'method' | 'decision' | 'other';

package/dist/judgment-value-proof.js

@@ -81,6 +81,23 @@ export function validateJudgmentValueProof(proof) {
         if (entry.layer !== undefined && !layers.includes(entry.layer)) {
             throw new TypeError(`unsupported decision.basis[].layer: ${String(entry.layer)}`);
         }
+        const source = entry.source;
+        if (source === undefined || source === null)
+            continue;
+        if (source.kind !== 'local_graph') {
+            throw new TypeError('decision.basis[].source.kind must be local_graph');
+        }
+        requiredText(source.entity_id, 'decision.basis[].source.entity_id');
+        if (source.entity_id !== entry.entity_id) {
+            throw new TypeError('decision.basis[].source.entity_id must match entity_id');
+        }
+        if (!['person', 'org', 'project', 'decision'].includes(source.entity_type)) {
+            throw new TypeError(`unsupported decision.basis[].source.entity_type: ${String(source.entity_type)}`);
+        }
+        if (source.version !== undefined && source.version !== null)
+            requiredText(source.version, 'decision.basis[].source.version');
+        if (source.digest !== undefined && source.digest !== null)
+            requiredText(source.digest, 'decision.basis[].source.digest');
     }
     const kind = proof.decision.judgment_kind;
     if (kind !== undefined && kind !== null) {

package/dist/knowledge-promotion.d.ts

@@ -3,7 +3,7 @@ export declare const KNOWLEDGE_PROMOTION_CONTRACT_VERSION: "knowledge_promotion.
 export declare const NORMALIZED_PROMOTION_SCHEMA_VERSION: "personal_knowledge_normalized.v1";
 export type PromotionApprovalKind = 'personal_share' | 'organization_candidate';
 export type PromotionSourceKind = 'personal_knowledge_v1' | 'organization_candidate';
-export type PromotionStatus = 'pending_owner_approval' | 'pending_org_review' | 'owner_rejected' | 'org_rejected' | 'org_accepted' | 'source_stale';
+export type PromotionStatus = 'pending_owner_approval' | 'pending_org_review' | 'owner_rejected' | 'org_rejected' | 'org_accepted' | 'source_stale' | 'source_withdrawn';
 export type PromotionDecision = 'approve' | 'reject';
 export type PromotionReviewAction = 'request' | 'owner_consent' | 'organization_review';
 export declare class KnowledgePromotionError extends Error {
@@ -72,8 +72,8 @@ export interface PromotionSourceRef {
     evidence_hash: string;
 }
 export interface PromotionDecisionRecord {
-    action: 'owner_consent' | 'organization_review';
-    decision: PromotionDecision;
+    action: 'owner_consent' | 'organization_review' | 'source_withdrawal';
+    decision: PromotionDecision | 'withdraw';
     actor_person_id: string;
     decided_at: string;
     receipt_id: string | null;
@@ -181,6 +181,36 @@ export interface KnowledgePromotionLineage {
     };
     created_at: string;
 }
+/** Append-only record of a share cancelled because the owner retracted the source memory. */
+export interface KnowledgePromotionWithdrawal {
+    withdrawal_id: string;
+    contract_version: typeof KNOWLEDGE_PROMOTION_CONTRACT_VERSION;
+    approval_kind: PromotionApprovalKind;
+    promotion_request_id: string;
+    source: PromotionSourceRef;
+    owner_person_id: string | null;
+    organization_id: string;
+    project_code: string;
+    previous_status: PromotionStatus;
+    organization_event_id: string | null;
+    graph_entity_id: string | null;
+    graph_withdrawn: boolean;
+    graph_outcome: 'not_promoted' | 'retracted' | 'projection_replaced';
+    withdrawn_by_person_id: string;
+    reason: string | null;
+    created_at: string;
+}
+export interface PromotedEntityWithdrawalInput {
+    request_id: string;
+    graph_entity_id: string;
+    organization_event_id: string | null;
+    organization_id: string;
+    project_code: string;
+    normalized_payload_hash: string;
+    withdrawal_id: string;
+    withdrawn_at: string;
+    reason: string | null;
+}
 export interface KnowledgePromotionStore {
     transaction<T>(work: (tx: unknown) => Promise<T>, options?: {
         principal: KnowledgePromotionPrincipal;
@@ -202,6 +232,9 @@ export interface KnowledgePromotionStore {
         organization_id: string;
         project_code: string;
     }, ctx: PromotionContext): Promise<void>;
+    /** Requests of one source visible to the caller, locked so a concurrent decision is ordered with the withdrawal. */
+    listRequestsBySource?(sourceKind: PromotionSourceKind, sourceId: string, ctx: PromotionContext): Promise<KnowledgePromotionRequest[]>;
+    recordWithdrawal?(withdrawal: KnowledgePromotionWithdrawal, ctx: PromotionContext): Promise<void>;
 }
 export interface KnowledgePromotionSources {
     readPersonalKnowledgeEvent?(eventId: string, ctx: PromotionContext): Promise<PersonalKnowledgeSourceRecord | null>;
@@ -249,6 +282,14 @@ export interface KnowledgePromotionGraphWriter {
     commitNormalizedPromotion(mutation: NormalizedGraphMutation, ctx: PromotionContext): Promise<{
         id: string;
     } | null>;
+    /**
+     * Mark the fact promoted by the request as retracted and out of retrieval. `projection_replaced` means
+     * another write has replaced the fact since, so it was left as it is.
+     */
+    withdrawPromotedEntity?(input: PromotedEntityWithdrawalInput, ctx: PromotionContext): Promise<{
+        id: string;
+        outcome: 'retracted' | 'projection_replaced';
+    } | null>;
 }
 export interface KnowledgePromotionPorts {
     store: KnowledgePromotionStore;
@@ -400,6 +441,23 @@ export declare class KnowledgePromotionService {
         principal: KnowledgePromotionPrincipal;
         authority?: KnowledgePromotionAuthority | null;
     }): Promise<KnowledgePromotionRequest>;
+    /**
+     * D4: the owner retracted a Personal Knowledge v1 memory. Cancel its shares that wait for a decision and
+     * withdraw an already promoted Graph fact from future retrieval. The approval lineage, the organization
+     * event, and the receipts stay. Retraction is the owner's right, so the organization review policy is
+     * not consulted and lost project access does not block it. Pass `tx` to commit with the retraction itself.
+     */
+    withdrawPersonalShares(input: {
+        personal_event_id: string;
+        reason?: string | null;
+    }, context: {
+        principal: KnowledgePromotionPrincipal;
+        tx?: unknown;
+    }): Promise<{
+        personal_event_id: string;
+        withdrawals: KnowledgePromotionWithdrawal[];
+    }>;
+    private withdrawRequest;
     private requirePolicy;
     private draftRequest;
     private authorize;

package/dist/knowledge-promotion.js

@@ -10,6 +10,10 @@
  *   task candidate, ...) → organization approval → Graph. It never takes the
  *   shape of an owner consent.
  *
+ * When the owner retracts the source memory, `withdrawPersonalShares` cancels
+ * the shares still waiting for a decision and withdraws an already promoted
+ * Graph fact from future retrieval, keeping the approval lineage and audit.
+ *
  * This module owns normalization, receipts, evidence, lineage, the Graph
  * mutation, and the state machine. Storage, the source readers, the knowledge
  * event kernel, the Graph writer, and the organization review policy (roles,
@@ -275,7 +279,8 @@ export function candidateApprovalReceipt(request, reviewerPersonId, reviewedAt)
     }).slice(0, 24)}`;
 }
 const DECISIONS = new Set(['approve', 'reject']);
-const TERMINAL = new Set(['owner_rejected', 'org_rejected', 'org_accepted', 'source_stale']);
+const TERMINAL = new Set(['owner_rejected', 'org_rejected', 'org_accepted', 'source_stale', 'source_withdrawn']);
+const WITHDRAWABLE = new Set(['pending_owner_approval', 'pending_org_review', 'org_accepted']);
 function sanitizePreview(value) {
     const text = String(value ?? '').trim().slice(0, 2000);
     if (!text || SECRET_OR_PRIVATE.test(text))
@@ -317,6 +322,11 @@ function requireHuman(principal) {
 function actorOf(principal) {
     return principal.actorPersonId || principal.personId;
 }
+function rejectWithdrawn(request) {
+    if (request.status === 'source_withdrawn') {
+        throw new KnowledgePromotionError('knowledge_promotion_source_withdrawn', 409, { request_id: request.request_id });
+    }
+}
 function requireProjectAccess(principal, projectCode) {
     if (!Array.isArray(principal.projectCodes) || !principal.projectCodes.includes(projectCode)) {
         throw new KnowledgePromotionError('knowledge_promotion_project_access_denied', 403);
@@ -572,6 +582,7 @@ export class KnowledgePromotionService {
                 throw new KnowledgePromotionError('knowledge_promotion_request_not_found', 404);
             }
             requireProjectAccess(principal, request.project_code);
+            rejectWithdrawn(request);
             const normalized = normalizePromotionPayload(request.normalized_payload).normalized;
             await this.authorize(policy, 'owner_consent', request, normalized, principal, context.authority ?? null, ctx);
             await this.claimAuthority(context.authority ?? null, request, 'owner_consent', ctx);
@@ -629,6 +640,8 @@ export class KnowledgePromotionService {
             if (request.approval_kind === 'personal_share' && request.owner_person_id === actor) {
                 throw new KnowledgePromotionError('knowledge_promotion_distinct_reviewer_required', 403);
             }
+            // The owner retracted the source memory; neither an approval nor a retried decision may pass.
+            rejectWithdrawn(request);
             if (request.status === 'pending_owner_approval' || request.status === 'owner_rejected') {
                 throw new KnowledgePromotionError('knowledge_promotion_owner_consent_required', 409);
             }
@@ -739,6 +752,104 @@ export class KnowledgePromotionService {
             throw new KnowledgePromotionError('knowledge_promotion_source_stale', 409, { request_id: requestId });
         return result;
     }
+    /**
+     * D4: the owner retracted a Personal Knowledge v1 memory. Cancel its shares that wait for a decision and
+     * withdraw an already promoted Graph fact from future retrieval. The approval lineage, the organization
+     * event, and the receipts stay. Retraction is the owner's right, so the organization review policy is
+     * not consulted and lost project access does not block it. Pass `tx` to commit with the retraction itself.
+     */
+    async withdrawPersonalShares(input, context) {
+        const principal = requireHuman(context.principal);
+        const read = this.ports.sources.readPersonalKnowledgeEvent;
+        if (typeof read !== 'function')
+            throw new KnowledgePromotionError('knowledge_promotion_personal_source_unavailable', 503);
+        const { listRequestsBySource, recordWithdrawal } = this.ports.store;
+        if (typeof listRequestsBySource !== 'function' || typeof recordWithdrawal !== 'function') {
+            throw new KnowledgePromotionError('knowledge_promotion_withdrawal_unavailable', 503);
+        }
+        const eventId = requireText(input?.personal_event_id, 'knowledge_promotion_source_id_required');
+        const reason = sanitizeReason(input?.reason);
+        const work = async (tx) => {
+            const ctx = { tx, principal };
+            const event = await read.call(this.ports.sources, eventId, ctx);
+            if (!event || event.owner_person_id !== principal.personId || event.organization_id !== principal.organizationId) {
+                throw new KnowledgePromotionError('knowledge_promotion_source_not_found', 404);
+            }
+            if (event.active)
+                throw new KnowledgePromotionError('knowledge_promotion_source_still_active', 409);
+            const requests = (await listRequestsBySource.call(this.ports.store, 'personal_knowledge_v1', eventId, ctx))
+                .filter((request) => request.approval_kind === 'personal_share'
+                && request.owner_person_id === principal.personId
+                && request.organization_id === principal.organizationId
+                && WITHDRAWABLE.has(request.status))
+                .sort((left, right) => left.request_id.localeCompare(right.request_id));
+            const withdrawals = [];
+            for (const request of requests) {
+                withdrawals.push(await this.withdrawRequest(request, reason, ctx));
+            }
+            return { personal_event_id: eventId, withdrawals };
+        };
+        return context.tx === undefined
+            ? this.ports.store.transaction(work, { principal })
+            : work(context.tx);
+    }
+    async withdrawRequest(request, reason, ctx) {
+        const withdrawnAt = this.now().toISOString();
+        const actor = actorOf(ctx.principal);
+        const withdrawalId = `kpw_${promotionSha256(`${request.request_id}:${request.source.version}:withdrawal`).slice(0, 24)}`;
+        let graphOutcome = 'not_promoted';
+        if (request.status === 'org_accepted') {
+            const withdraw = this.ports.graph.withdrawPromotedEntity;
+            if (typeof withdraw !== 'function')
+                throw new KnowledgePromotionError('knowledge_promotion_withdrawal_unavailable', 503);
+            const result = await withdraw.call(this.ports.graph, {
+                request_id: request.request_id,
+                graph_entity_id: requireText(request.graph_entity_id, 'knowledge_promotion_graph_entity_required'),
+                organization_event_id: request.organization_event_id,
+                organization_id: request.organization_id,
+                project_code: request.project_code,
+                normalized_payload_hash: request.normalized_payload_hash,
+                withdrawal_id: withdrawalId,
+                withdrawn_at: withdrawnAt,
+                reason,
+            }, ctx);
+            if (!result?.id || (result.outcome !== 'retracted' && result.outcome !== 'projection_replaced')) {
+                throw new KnowledgePromotionError('knowledge_promotion_graph_withdrawal_failed', 409, { request_id: request.request_id });
+            }
+            graphOutcome = result.outcome;
+        }
+        const updated = await this.ports.store.updateRequest(request.request_id, {
+            status: 'source_withdrawn',
+            decisions: [...request.decisions, {
+                    action: 'source_withdrawal', decision: 'withdraw', actor_person_id: actor, decided_at: withdrawnAt,
+                    receipt_id: withdrawalId, reason,
+                }],
+            updated_at: withdrawnAt,
+        }, { expectedRevision: request.revision }, ctx);
+        if (!updated)
+            throw new KnowledgePromotionError('knowledge_promotion_state_conflict', 409);
+        const withdrawal = {
+            withdrawal_id: withdrawalId,
+            contract_version: KNOWLEDGE_PROMOTION_CONTRACT_VERSION,
+            approval_kind: request.approval_kind,
+            promotion_request_id: request.request_id,
+            source: request.source,
+            owner_person_id: request.owner_person_id,
+            organization_id: request.organization_id,
+            project_code: request.project_code,
+            previous_status: request.status,
+            organization_event_id: request.organization_event_id,
+            graph_entity_id: request.graph_entity_id,
+            graph_withdrawn: graphOutcome === 'retracted',
+            graph_outcome: graphOutcome,
+            withdrawn_by_person_id: actor,
+            reason,
+            created_at: withdrawnAt,
+        };
+        await this.ports.store.recordWithdrawal
+            .call(this.ports.store, withdrawal, ctx);
+        return withdrawal;
+    }
     requirePolicy() {
         if (!this.ports.reviewPolicy || typeof this.ports.reviewPolicy.authorize !== 'function') {
             throw new KnowledgePromotionError('knowledge_promotion_review_policy_unavailable', 503);

package/dist/local-web-host.d.ts

@@ -100,10 +100,10 @@ export declare function createLocalObjectiveDefinitionBuilder(now: () => Date):
  */
 export declare function createObjectiveFoundationModule(context: LocalWebModuleContext): LocalWebModule;
 /**
- * Read-only World Model routes.  Writes (observations, corrections, model
- * adoption) are not on the Web in v1.  Without an approval reader an approved
- * adoption cannot be verified, so only the adoptions route reports
- * `approval_reference_unresolved`; the other routes stay readable.
+ * World Model routes.  Reads retain the explicit absence/partial contract;
+ * the first-user Web entry writes only a trusted Variable definition and an
+ * initial Observation. Models, adoption and corrections stay out of this
+ * focused route until their own authority and review contract exists.
  */
 export declare function createWorldModelReadModule(context: LocalWebModuleContext): LocalWebModule;
 /**