@unson/brainbase-mcp 0.11.0 → 0.12.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-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;
 /**

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Local-first Brainbase judgment OS that lets supported AI agents reuse a user's approved goals, priorities, decisions, and judgment criteria.",
   "type": "module",
   "license": "MIT",
@@ -348,5 +348,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "070f39f8014fbbe224bb4615ef89999aeeb8d0a5"
+  "gitHead": "084154257b751ba7bf6b303aa889c42ac551c9b9"
 }

package/ui/graph-registry-view.js

@@ -163,6 +163,7 @@ function textCell(value, fallback) {
  * @param {string} [options.token] Launch token sent with a correction.
  * @param {string} [options.tokenHeader] Header name for the token.
  * @param {boolean} [options.autoLoad=true] Runs the empty search and reads the kinds on mount.
+ * @param {string} [options.initialEntityId] Opens this exact entity after the initial Graph read.
  * @param {() => Date} [options.now] The owner's clock.
  * @param {boolean} [options.canCorrect=true] When false, no correction control is drawn anywhere
  *   (この記録を直す, 関係を加える, この関係を直す, and この画面で直せること under the kinds of
@@ -204,6 +205,7 @@ export function createGraphRegistryView({
   token,
   tokenHeader,
   autoLoad = true,
+  initialEntityId,
   now = () => new Date(),
   canCorrect = true,
   correctionScope,
@@ -617,6 +619,23 @@ export function createGraphRegistryView({
       const canFix = scope.entity(entity.type) && scope.fields(graphEntityCorrectionFields(entity.type)).length > 0;
       const relatable = newRelationOptions(entity.type).length > 0;
       const related = loaded.outgoing.length + loaded.incoming.length > 0;
+      const correctionEntries = [
+        canFix ? '「この記録を直す」' : null,
+        relatable && scope.createEdges ? '「関係を加える」' : null,
+        related && scope.edges ? '関係ごとの「この関係を直す」' : null,
+      ].filter(Boolean);
+      if (correctionEntries.length > 0) {
+        const lastEntry = correctionEntries.at(-1);
+        const entries = correctionEntries.length === 1
+          ? lastEntry
+          : `${correctionEntries.slice(0, -1).join('、')}、または${lastEntry}`;
+        children.push(workspaceRailBlock(doc, {
+          title: '訂正の流れ',
+          content: makeElement(doc, 'p', {
+            text: `誤りを見つけたときの訂正入口です。${entries}から変更案を入力します。承認待ちの提出ではなく、保存するとその場でGraphに反映され、理由と変更前後が履歴に残ります。保存後に読み直して一致を確かめ、確認できた内容は、次のMCPの search・get_context・resolve_entity で使われます。`,
+          }),
+        }));
+      }
       const actions = [
         canFix ? workspaceButton(doc, { text: 'この記録を直す', onClick: () => openCorrection('entity', () => correction.openEntity(entity, { title: 'この記録を直す' })) }) : null,
         relatable && scope.createEdges
@@ -797,7 +816,14 @@ export function createGraphRegistryView({
     },
   };
   controller.render();
-  if (autoLoad) void controller.load();
+  if (autoLoad) {
+    void controller.load().then(() => {
+      if (initialEntityId) return controller.openEntity(initialEntityId);
+      return undefined;
+    });
+  } else if (initialEntityId) {
+    void controller.openEntity(initialEntityId);
+  }
   return controller;
 }