@unson/brainbase-mcp 0.10.15 → 0.12.0

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;
 /**

package/dist/local-web-host.js

@@ -10,7 +10,7 @@ import { createFoundationRevisionStore, FoundationStoreError } from './foundatio
 import { createGraphWebHttpHandler } from './graph-web-http.js';
 import { defaultJudgmentJournalRoot } from './judgment-value-proof-review.js';
 import { nodeRequestToFetch, writeFetchResponse } from './local-web-fetch-bridge.js';
-import { assertSameOrigin, isLoopbackHost, LOCAL_WEB_CONTENT_SECURITY_POLICY, LocalWebHttpError, requestUrl, tokenMatches, writeHttpError, writeJson } from './local-web-security.js';
+import { assertSameOrigin, isLoopbackHost, LOCAL_WEB_CONTENT_SECURITY_POLICY, LocalWebHttpError, readJsonObjectBody, requestUrl, tokenMatches, writeHttpError, writeJson } from './local-web-security.js';
 import { resolveDataDir } from './paths.js';
 import { loadPersonalOs, readPersonalOsSidecar } from './ssot.js';
 import { createValueProofReviewHttpHandler, VALUE_PROOF_REVIEW_TOKEN_HEADER } from './value-proof-review-http.js';
@@ -437,7 +437,7 @@ function worldModelError(error) {
     }
     if (error instanceof LocalWebHttpError)
         return error;
-    return new LocalWebHttpError(500, 'internal_error', 'World model read failed');
+    return new LocalWebHttpError(500, 'internal_error', 'World model request failed');
 }
 async function listReadableSidecarRecords(input) {
     try {
@@ -473,11 +473,112 @@ async function listReadableSidecarRecords(input) {
     }
     return { records, unreadable: { count, codes: [...codes] } };
 }
+const LOCAL_WEB_WORLD_MODEL_SCOPE_START = '1970-01-01T00:00:00.000Z';
+const WORLD_MODEL_VALUE_KINDS = new Set(['number', 'boolean', 'string', 'state']);
+const WORLD_MODEL_AGGREGATIONS = new Set(['none', 'sum', 'average', 'count', 'min', 'max', 'last', 'custom']);
+const WORLD_MODEL_VARIABLE_FIELDS = new Set([
+    'meaning', 'subject', 'valueKind', 'unit', 'aggregation', 'granularity', 'measurementMethod'
+]);
+const WORLD_MODEL_OBSERVATION_FIELDS = new Set(['variableRef', 'value']);
+const WORLD_MODEL_AUTHORITY_FIELDS = new Set([
+    'acl', 'scope', 'storage', 'provenance', 'authorizedUses', 'ownerId', 'readerIds', 'writerIds',
+    'principal', 'subjectId', 'recordedAt', 'occurredAt', 'period', 'id', 'revision', 'type'
+]);
+function worldModelInvalid(message) {
+    return new LocalWebHttpError(400, 'invalid_input', message);
+}
+function assertWorldModelBodyFields(body, allowed) {
+    for (const key of Object.keys(body)) {
+        if (allowed.has(key))
+            continue;
+        if (WORLD_MODEL_AUTHORITY_FIELDS.has(key)) {
+            throw new LocalWebHttpError(400, 'authority_field_in_body', `${key} is decided by the local Web host`);
+        }
+        throw worldModelInvalid(`Unknown World Model field ${key}`);
+    }
+}
+function requiredWorldModelText(body, key) {
+    const value = body[key];
+    if (typeof value !== 'string' || value.trim() === '')
+        throw worldModelInvalid(`${key} is required`);
+    return value.trim();
+}
+function worldModelVariableFromBody(body, principal) {
+    assertWorldModelBodyFields(body, WORLD_MODEL_VARIABLE_FIELDS);
+    const valueKind = requiredWorldModelText(body, 'valueKind');
+    if (!WORLD_MODEL_VALUE_KINDS.has(valueKind))
+        throw worldModelInvalid(`Unknown valueKind ${valueKind}`);
+    const aggregation = requiredWorldModelText(body, 'aggregation');
+    if (!WORLD_MODEL_AGGREGATIONS.has(aggregation))
+        throw worldModelInvalid(`Unknown aggregation ${aggregation}`);
+    const unit = body.unit === undefined ? undefined : requiredWorldModelText(body, 'unit');
+    if (valueKind === 'number' && !unit)
+        throw worldModelInvalid('unit is required for number variables');
+    return {
+        id: `web.variable.${randomBytes(10).toString('hex')}`,
+        type: 'variable',
+        revision: '1',
+        meaning: requiredWorldModelText(body, 'meaning'),
+        epistemicState: 'unverified',
+        adoptionState: 'draft',
+        authorizedUses: ['draft', 'judgment', 'evaluation'],
+        acl: { ownerId: principal, visibility: 'private', readerIds: [], writerIds: [] },
+        storage: 'ontology',
+        provenance: [{ sourceId: LOCAL_WEB_PROVENANCE_SOURCE_ID, sourceKind: 'observation', evidenceIds: [] }],
+        scope: { subjectIds: [principal], validFrom: LOCAL_WEB_WORLD_MODEL_SCOPE_START },
+        subject: requiredWorldModelText(body, 'subject'),
+        valueKind: valueKind,
+        ...(unit ? { unit } : {}),
+        aggregation: aggregation,
+        granularity: requiredWorldModelText(body, 'granularity'),
+        measurementMethod: requiredWorldModelText(body, 'measurementMethod'),
+        // The local host stamps the current date into observations; a broad owner-only
+        // validity window avoids asking the first-time user for hidden scope fields.
+    };
+}
+function worldModelReference(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw worldModelInvalid('variableRef is required');
+    const reference = value;
+    if (reference.type !== 'variable' || typeof reference.id !== 'string' || reference.id.trim() === ''
+        || typeof reference.revision !== 'string' || !/^[1-9]\d*$/u.test(reference.revision)) {
+        throw worldModelInvalid('variableRef must reference a variable revision');
+    }
+    if (Object.keys(reference).some((key) => !['id', 'type', 'revision'].includes(key))) {
+        throw worldModelInvalid('variableRef contains an unsupported field');
+    }
+    return { id: reference.id.trim(), type: 'variable', revision: reference.revision };
+}
+function worldModelObservationFromBody(body, principal, now) {
+    assertWorldModelBodyFields(body, WORLD_MODEL_OBSERVATION_FIELDS);
+    if (!Object.hasOwn(body, 'value') || body.value === null || body.value === undefined)
+        throw worldModelInvalid('value is required');
+    const value = body.value;
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+        throw worldModelInvalid('value must be a string, number, or boolean');
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw worldModelInvalid('value must be a finite number');
+    }
+    const nowIso = now.toISOString();
+    const day = nowIso.slice(0, 10);
+    const observationId = `web.observation.${randomBytes(10).toString('hex')}`;
+    return {
+        id: observationId,
+        variableRef: worldModelReference(body.variableRef),
+        subjectId: principal,
+        value,
+        occurredAt: nowIso,
+        period: { from: `${day}T00:00:00.000Z`, until: `${day}T23:59:59.999Z` },
+        recordedAt: nowIso,
+        sourceRef: { sourceId: LOCAL_WEB_PROVENANCE_SOURCE_ID, sourceKind: 'observation', evidenceIds: [observationId] }
+    };
+}
 /**
- * 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 function createWorldModelReadModule(context) {
     const foundationStore = createFoundationRevisionStore({ dataDir: context.dataDir });
@@ -519,17 +620,39 @@ export function createWorldModelReadModule(context) {
                 writeJson(response, 404, { error: { code: 'not_found', message: 'Not found' } });
                 return true;
             }
-            if (request.method !== 'GET') {
-                writeJson(response, 405, { error: { code: 'method_not_allowed', message: 'The world model is read-only here' } });
-                return true;
-            }
             const graph = await readLocalGraphState(context.dataDir);
             if (graph.status !== 'ready' || !graph.ownerId) {
                 writeGraphUnavailable(response, graph, context.dataDir);
                 return true;
             }
+            const principal = { principal: graph.ownerId };
+            if (request.method === 'POST' && (resource === 'variables' || resource === 'observations')) {
+                try {
+                    const body = await readJsonObjectBody(request, LOCAL_WEB_FOUNDATION_BODY_LIMIT_BYTES);
+                    if (resource === 'variables') {
+                        const definition = worldModelVariableFromBody(body, graph.ownerId);
+                        const reference = await worldModel.createVariable(definition, principal);
+                        writeJson(response, 201, {
+                            reference: { id: reference.id, type: reference.type, revision: reference.revision },
+                            digest: reference.digest
+                        });
+                    }
+                    else {
+                        const observation = await worldModel.saveObservation(worldModelObservationFromBody(body, graph.ownerId, context.now()), principal);
+                        writeJson(response, 201, { observation });
+                    }
+                }
+                catch (error) {
+                    writeHttpError(response, worldModelError(error));
+                }
+                return true;
+            }
+            if (request.method !== 'GET') {
+                writeJson(response, 405, { error: { code: 'method_not_allowed', message: 'この入口では変数と観測値を登録できます' } });
+                return true;
+            }
             try {
-                writeJson(response, 200, await read(resource, { principal: graph.ownerId }));
+                writeJson(response, 200, await read(resource, principal));
             }
             catch (error) {
                 writeHttpError(response, worldModelError(error));
@@ -619,7 +742,9 @@ if (extensionScreens.some((screen, index) => screen?.id !== extensionIds[index]
   throw new Error('Invalid extension screen id');
 }
 const meta = (name) => document.querySelector(\`meta[name="\${name}"]\`)?.getAttribute('content') ?? '';
-const screenFromHash = () => decodeURIComponent(location.hash.replace(/^#/, '')) || undefined;
+// Keep the query portion intact; the shell parses the Graph entity query and
+// only treats the entity id as a target of the Graph screen.
+const screenFromHash = () => location.hash.replace(/^#/, '') || undefined;
 const shell = createLocalWebShell({
   root: document.getElementById('brainbase-local-web'),
   token: meta('brainbase-web-token'),

package/dist/server-support.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Small HTTP-host helpers shared by Brainbase servers: a structured error with
+ * client-safe JSON, an async route wrapper, and a JSON logger that masks
+ * secrets. They carry no organization, tenant, or deployment concept.
+ */
+type UnknownRecord = Record<string, unknown>;
+export interface ErrorCodeEntry {
+    code: string;
+    statusCode: number;
+}
+/** Standard error codes. `code` is safe to expose to clients. */
+export declare const ErrorCodes: {
+    VALIDATION_ERROR: {
+        code: string;
+        statusCode: number;
+    };
+    INVALID_DATE_FORMAT: {
+        code: string;
+        statusCode: number;
+    };
+    MISSING_REQUIRED_FIELD: {
+        code: string;
+        statusCode: number;
+    };
+    UNSUPPORTED_FORMAT: {
+        code: string;
+        statusCode: number;
+    };
+    UNAUTHORIZED: {
+        code: string;
+        statusCode: number;
+    };
+    FORBIDDEN: {
+        code: string;
+        statusCode: number;
+    };
+    CROSS_TENANT_CANDIDATE: {
+        code: string;
+        statusCode: number;
+    };
+    PROJECT_NOT_FOUND: {
+        code: string;
+        statusCode: number;
+    };
+    SESSION_NOT_FOUND: {
+        code: string;
+        statusCode: number;
+    };
+    TASK_NOT_FOUND: {
+        code: string;
+        statusCode: number;
+    };
+    SCHEDULE_NOT_FOUND: {
+        code: string;
+        statusCode: number;
+    };
+    WORKTREE_NOT_FOUND: {
+        code: string;
+        statusCode: number;
+    };
+    EVENT_NOT_FOUND: {
+        code: string;
+        statusCode: number;
+    };
+    CONFLICT: {
+        code: string;
+        statusCode: number;
+    };
+    PORT_IN_USE: {
+        code: string;
+        statusCode: number;
+    };
+    INTERNAL_ERROR: {
+        code: string;
+        statusCode: number;
+    };
+    DATABASE_ERROR: {
+        code: string;
+        statusCode: number;
+    };
+    PROJECT_CATALOG_UNAVAILABLE: {
+        code: string;
+        statusCode: number;
+    };
+    TIMEOUT: {
+        code: string;
+        statusCode: number;
+    };
+};
+export interface AppErrorOptions {
+    details?: UnknownRecord | null;
+    cause?: unknown;
+}
+export interface AppErrorLog {
+    code: string;
+    message: string;
+    statusCode: number;
+    timestamp: string;
+    details?: UnknownRecord;
+    cause?: string;
+}
+/** A structured error: the message and code go to clients, details stay in logs. */
+export declare class AppError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly timestamp: string;
+    readonly details: UnknownRecord | null;
+    cause?: unknown;
+    constructor(message: string, errorCode: ErrorCodeEntry, options?: AppErrorOptions);
+    /** Client-safe JSON. It never includes details. */
+    toJSON(): {
+        error: {
+            code: string;
+            message: string;
+            timestamp: string;
+        };
+    };
+    /** Log object, including details and the cause message. */
+    toLog(): AppErrorLog;
+    static isAppError(error: unknown): error is AppError;
+    static notFound(resource: string, id: string): AppError;
+    static validation(message: string, details?: UnknownRecord): AppError;
+    static unauthorized(message?: string): AppError;
+    static forbidden(message?: string, details?: UnknownRecord): AppError;
+    static conflict(message: string, details?: UnknownRecord): AppError;
+    static internal(message?: string, cause?: Error): AppError;
+}
+type RouteHandler = (req: any, res: any, next: (error?: unknown) => unknown) => unknown;
+/** Wraps an async route handler so that a rejection reaches the error middleware. */
+export declare function asyncHandler(fn: RouteHandler): (req: any, res: any, next: (error?: unknown) => unknown) => void;
+/** JSON-line logger that masks secrets. DEBUG enables debug lines. */
+export declare const logger: {
+    info(msg: string, data?: UnknownRecord): void;
+    warn(msg: string, data?: UnknownRecord): void;
+    error(msg: string, data?: Error | (UnknownRecord & {
+        error?: unknown;
+    })): void;
+    debug(msg: string, data?: UnknownRecord): void;
+};
+export {};