hypothesis-proximity-update

name: hypothesis-proximity-update description: Update hypothesis proximity state by invoking the canonical embedding bridge for one hypothesis.

Goal:

Update hypothesis proximity state by invoking the canonical embedding bridge for one hypothesis.

Inputs:

optional existing state/PROXIMITY_GRAPH.json
target hypothesis_id
run-frozen embedding provider settings from state/RESOLVED_RUN_CONFIG.json

Outputs:

updated state/proximity_receipts/<hypothesis_id>.json
updated state/PROXIMITY_STATUS.json
updated in-memory ProximityGraphContract
updated state/PROXIMITY_GRAPH.json when the provider returns a valid embedding
updated state/PIPELINE_STATE.json
updated state/CURRENT_STAGE.json

Context Loading:

Open skills/shared-references/schema-index.md.
Read packages/agent_contracts/state.py and confirm the exact ProximityGraphContract shape before writing state/PROXIMITY_GRAPH.json.
Read packages/agent_contracts/proximity.py and confirm the proximity receipt and status schemas before interpreting provider outcomes.
Read packages/agent_contracts/pipeline_runtime.py before updating state/PIPELINE_STATE.json or state/CURRENT_STAGE.json.
Load the current proximity graph if it exists. If it does not exist yet, start from an empty ProximityGraphContract.
Treat embedding generation as a bridge/tool concern. Host agents must not generate, infer, paste, or hand-write numeric embeddings in prompt output.
Do not skip this skill merely because no embedding vector is already present in the execution context.

Execution Contract:

This skill is deterministic and must not call an LLM.
Use from tools import sync_pipeline_stage_artifacts as the canonical paired write surface for entering the Proximity substage.
On entry, call tools.sync_pipeline_stage_artifacts(run_dir, current_phase="Proximity", current_skill="hypothesis-proximity-update").
Use from tools import update_hypothesis_proximity as the stable invocation surface.
The exported bridge is implemented in packages/agent_mechanics/hypothesis_embedding.py.
The canonical hypothesis-to-embedding text formatter is implemented in packages/agent_mechanics/hypothesis_embedding_text.py.
The helper signature is update_hypothesis_proximity(run_dir, hypothesis_id, config=None, provider=None) -> ProximityEmbeddingReceiptContract.
The bridge formats the hypothesis text, reads the run-frozen proximity provider settings from state/RESOLVED_RUN_CONFIG.json unless an explicit test config is passed, calls the configured provider when enabled, records a proximity receipt/status, and updates state/PROXIMITY_GRAPH.json only when a valid embedding is returned.
Provider-specific backends such as openai_compatible and gemini must remain behind tools.update_hypothesis_proximity(...); host agents must not call provider SDKs directly or paste provider-returned vectors into artifacts.
The lower-level graph helper remains tools.update_proximity_graph(...), implemented in packages/agent_mechanics/proximity_update.py; host agents must not call it with prompt-fabricated vectors.
This skill must not hand-write embeddings, infer embeddings from hypothesis prose, or fabricate placeholder numeric vectors.
If the provider is disabled, unavailable, invalid, or fails, preserve the bridge-written receipt/status, do not fabricate a graph update, and return control to ranking with receipt-gated fallback semantics.

Execution Steps:

Open skills/shared-references/schema-index.md, then read packages/agent_contracts/state.py, packages/agent_contracts/proximity.py, and packages/agent_contracts/pipeline_runtime.py before writing proximity or run-level stage artifacts.
Before running the bridge, call tools.sync_pipeline_stage_artifacts(run_dir, current_phase="Proximity", current_skill="hypothesis-proximity-update").
Confirm the target hypothesis_id identifies an existing canonical hypotheses/<id>/HYPOTHESIS.json artifact.
Call tools.update_hypothesis_proximity(run_dir, hypothesis_id) exactly once for the target hypothesis.
Inspect the returned ProximityEmbeddingReceiptContract and the persisted state/proximity_receipts/<hypothesis_id>.json.
If the receipt status is succeeded, validate the updated state/PROXIMITY_GRAPH.json.
If the receipt status is skipped_disabled, skipped_provider_unavailable, failed_provider_error, or failed_invalid_embedding, preserve the receipt/status and return control to ranking. Do not infer or fabricate placeholder embeddings from text, IDs, or manual feature heuristics.
Validate the updated receipt/status artifacts before declaring completion.

Artifact Rules:

state/PROXIMITY_GRAPH.json must remain the canonical persisted graph artifact.
state/proximity_receipts/<hypothesis_id>.json is the canonical per-hypothesis embedding bridge receipt.
state/PROXIMITY_STATUS.json is the canonical run-level proximity bridge status artifact.
Similarity edges must stay symmetric across both hypothesis IDs.
Each persisted graph embedding should include metadata for provider, model, dimensions, input text hash, and embedding config hash.
If the graph already contains the target hypothesis ID with the same embedding input hash and embedding config hash, the bridge may confirm the existing state through a succeeded receipt with graph_updated=false; do not duplicate entries.
If the graph already contains the target hypothesis ID with different or missing input/config metadata, preserve the bridge receipt and do not overwrite the existing embedding in prompt code.
Placeholder embeddings, manually engineered stand-in vectors, or prose-derived pseudo-embeddings must never be written into the canonical graph artifact.

Completion Rule:

This skill is complete only when tools.update_hypothesis_proximity(run_dir, hypothesis_id) has returned a persisted receipt and either state/PROXIMITY_GRAPH.json validates after a succeeded receipt or the receipt/status explicitly records why the graph was not updated.