Crate sim_lib_forge

Expand description

Compiled intent records, BRIDGE lifts, and reusable packet-program lookup.

sim-lib-forge is the FORGE intent compiler: it turns a plain-English task into a reusable, verified, cached BRIDGE packet-program. It sits on top of the BRIDGE envelope (sim-codec-bridge + sim-lib-bridge) and adds the compile / verify / cache / route layer around it. Nothing here is agent-specific – a compiled intent is an ordinary SIM value any caller can run.

§Pipeline

prose
  -> lift        `forge_lift_once` | `forge_lift_frontier`  (prose -> candidate BridgePacket)
  -> type check  `assert_return_shape_parses`               (a lift MUST type its own output)
  -> rx check    (BRIDGE structural validation, from sim-lib-bridge)
  -> verify      `verify_answer` over a `VerifyCatalog`     (assertion | judge | evidence)
  -> promote     `PromotePolicy`                            (Candidate -> Verified -> Golden)
  -> store       `IntentLibrary`                            (named index over the content store)
  -> resolve     `forge_resolve`                            (a Golden hit skips the model)
  -> route       `run_intent_routed`                        (cheap-first, escalate on failure)

§Key API

Artifact: CompiledIntent / IntentStatus (name, version, source-prose cid, packet cid, verifier ids, approval state) and IntentLibrary, the named index that makes reuse a lookup instead of a recompile.
Lift: forge_lift_once (one-shot) and forge_lift_frontier (built part-by-part through the shared BRIDGE frontier, each step flat-grammar-constrained and checked), with normalize_prose and assert_return_shape_parses.
Reuse: forge_resolve / ForgeResolver / PromotePolicy – a matching Golden intent is fetched instead of re-lifted.
Verify: verify_answer / Verifier / VerifyCatalog – assertion, judge (a BRIDGE COLLAB vote), and evidence checks, so the checker catches a well-formed but wrong answer, not only a malformed one.
Route: run_intent_routed / RoutePolicy – run a cheap model first and escalate on verifier failure (the safe model downshift).
Measure: run_eval / EvalCase / standard_eval_corpus – accuracy, token cost, and model-call count across raw / compiled / cached / downshifted arms.
Grow: propose_frame extends the BRIEF frame vocabulary from unmapped intent; forge_verb / ForgeLib is the sim forge Bootloader verb (lift -> review the inferred Shape -> promote -> run).

§Why compile prose at all

The compiler is itself a model, so a lift is a candidate, never trusted on sight: it is validated by the BRIDGE checker and only promoted to a reusable Golden once it passes. Precision comes from freezing and typing the contract (a checked return Shape, owned instruction text, no injection channel); speed comes from caching the Golden (a hit skips inference entirely) and from downshifting to a cheaper model behind a checker that actually catches wrong. The model never gets smarter – the envelope gets reliable and the artifact gets reused.

Named out of scope: semantic prose lookup. normalize_prose keys reuse on a byte-level normal form, not on meaning, so two differently-worded but equivalent prompts do not share a Golden.

Structs§

ArmMetrics: Metrics aggregated for one eval arm.
AuthorArmMetrics: Metrics aggregated for one authoring arm.
AuthorBenchReport: Report for a full offline authoring benchmark run.
AuthorCase: One deterministic authoring case.
AuthorOutcome: Result of a contract-native authoring run.
AuthorTask: One contract-native authoring task to send to a model runner.
CompiledIntent: Named, versioned wrapper around a structurally checked BRIDGE packet.
ContractCard: A compact, source-free model-facing contract for one loaded export.
ContractDeck: A stable, ordered deck of runtime contract cards and assembly diagnostics.
ContractDeckCache: Cached runtime contract deck keyed by a cheap registry generation marker.
ContractProjection: A token-counted model-facing projection of ranked contract cards.
ContractProjectionCaps: Limits and format switches for contract projection.
ContractQueryReport: Counters and query facts from the most recent contract-deck query.
EvalArm: One eval arm configuration.
EvalCase: One committed FORGE eval case.
EvalCassette: Deterministic cassette rows for one eval case.
EvalPlayback: Recorded model answer and token cost for one deterministic eval playback.
EvalReport: Eval report across all requested arms.
ForgeLib: Loadable FORGE command library.
ForgeResolver: Stateful FORGE resolver with an intent library index.
FrameSpecProposal: Candidate frame specification inferred from prose that has no registered frame.
IntentLibrary: Named index for compiled intent artifacts.
LiftOptions: Options for one FORGE prose-to-packet lift.
RankedContractCard: One contract card paired with its ranking score and explanation.
RouteAttempt: One target attempt made by the router.
RoutePolicy: Cost-aware route policy for a compiled intent call.
RouteProvenance: Provenance for the routed answer.
RouteTarget: One eval target in a cost-ordered route ladder.
RoutedAnswer: Answer plus route provenance and attempt details.
ShapeQuery: Shape filters for contract-card retrieval.
VerifyCatalog: Local catalog binding verifier ids, probes, and cited ground truth.
VerifyFailure: One failed semantic verifier.
VerifyProbe: Concrete case that proves a compiled intent against required verifiers.
VerifyReport: Semantic verification result for one answer or probe set.

Enums§

AuthorArm: Contract-native authoring arms measured by run_author_bench.
ContractGap: A missing or synthesized part of a ContractCard.
IntentStatus: Verification and approval state for a compiled intent artifact.
ProbeOracle: Oracle backing a concrete verification probe.
PromotePolicy: Promotion rule applied after a resolve miss lifts a fresh candidate.
RouteAttemptStatus: Status for one route attempt.
Verifier: Semantic verifier registered for a compiled intent.

Constants§

CONTRACT_PROJECTION_EXTRA: Model-request extension key for the fenced projected contract payload.
OUTPUT_GRAMMAR_GRAPH_EXTRA: Model-request extension key for source SG3 grammar graph metadata.

Statics§

RECIPES: Cookbook recipes embedded from this crate’s recipes/ directory.

Functions§

approve_frame_proposal: Registers a human-approved proposal in book and returns the new book id.
assemble_contract_deck: Assembles a source-free contract deck from the live registry and browse Cards.
assert_return_shape_parses: Verifies that a compiled packet declares a parseable return Shape.
author_model_request: Builds a grammar-bearing model request from a task and projected contracts.
authorized_capabilities: Returns the sorted union of capabilities authorized by projected cards.
contract_card_from_expr: Decodes a ContractCard from data that checks against contract_card_shape.
contract_card_shape: The Shape a ContractCard::as_expr value conforms to.
estimate_prompt_tokens: Estimates prompt tokens with the FORGE baseline semantic-token counter.
forge_entrypoint_symbol: Entrypoint symbol claimed by the loadable forge command library.
forge_lift_frontier: Compiles prose into a checked candidate packet by authoring one BRIDGE part at a time through the shared frontier menu.
forge_lift_once: Compiles prose into a structurally checked candidate BRIDGE packet artifact.
forge_resolve: Resolves prose through an empty in-memory intent library.
forge_resolve_with_options: Resolves prose through an explicit library and lift options.
forge_verb: Runs the FORGE command verb and returns a structured report expression.
normalize_prose: Normalizes prose into the byte-level source identity used by FORGE.
project_contracts: Projects ranked contract cards into a bounded, token-counted prompt payload.
propose_frame: Proposes a typed frame spec for prose that has no registered frame.
proposed_frame_part: Builds a normative frame part from an approved proposal and matching prose.
query_contract_deck: Query a cached FORGE contract deck by argument and result Shape.
run_author_bench: Runs the offline authoring benchmark with deterministic fakes only.
run_author_task: Runs one contract-native authoring task through routing, checks, realization, and cassette capture.
run_eval: Runs the corpus against the requested eval arms.
run_intent_routed: Runs a compiled intent through a cost-aware route ladder and returns only the accepted decoded answer.
run_intent_routed_report: Runs a compiled intent through a cost-aware route ladder and returns route provenance with the accepted decoded answer.
semantic_tokens: Splits prose into the semantic token stream used by FORGE prompt budgets.
standard_author_arms: Returns the standard offline authoring benchmark arms.
standard_author_cases: Returns the standard offline authoring corpus.
standard_eval_arms: Returns the standard FORGE eval arms.
standard_eval_corpus: Returns the committed network-free FORGE eval corpus.
store_packet_artifact: Stores a BRIDGE packet artifact in the context datum store and returns its canonical packet content id.
verify_answer: Runs semantic verification with an empty catalog.