…le, architecture docs

Implements polish points for M-DX4 completion to enhance traceability:

**CLAUDE.md**:
- Added CoreTypeInfo invariant as Critical Principle #3 (+44 LOC)
- Documents validation contract enforcement at 3 sites
- Includes error examples and monomorphization compatibility

**CHANGELOG.md**:
- Added benchmark summary table with 5 benchmarks
- Quantifies negligible overhead: <35μs for 1000 nodes
- Analysis shows O(n) linear scaling confirmed

**docs/architecture/types.md** (NEW - 195 LOC):
- Comprehensive type system architecture documentation
- Cross-references to validator implementation
- Documents CoreTypeInfo invariant with enforcement details
- Includes future monomorphization compatibility notes

All polish points completed as suggested by user.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

M-CODEGEN-VALUE-TYPES bug fix #3: writeADTSliceConverters now checks
if a type in adtSliceTypes is actually a value-type record.

Root cause: adtSliceTypes collects ALL user-defined types that appear
in list fields, including record types like Tile. Previously, these
always generated []*Type converters even when the record is a value type.

Now checks g.recordTypes to see if the type has TypeCategoryValue, and
generates []Type with e.(Type) assertions for value types.

Fixes: ConvertToTileSlice returning []*Tile when []Tile expected

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Updated 7 files to document the three-way import distinction:
  ./plan              — local sibling (same package)
  pkg/vendor/name/mod — external dependency
  std/module          — stdlib

Files updated:
- .claude/skills/ailang-packages/SKILL.md: Rule #2 rewritten for ./
- .claude/skills/ailang-packages/resources/error_solutions.md: LDR001 fix updated
- .claude/skills/ailang-packages/resources/manifest_reference.md: Import conventions section
- .claude/skills/use-ailang/resources/syntax_quick_ref.md: New Imports section
- docs/docs/guides/packages.md: Common Pitfalls #3 rewritten
- docs/docs/reference/modules.md: Import Syntax section with three forms
- changelogs/v0.9-current.md: M-DX-RELIMPORT entry in v0.9.12

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Findings from v0.14.2 baseline (1,178 runs):

1. Prompt update (`prompts/v0.12.1.md`): strengthen Rule #3 of "Required
   Program Structure" with bidirectional `=`-body / `{ }`-body guidance.
   Models repeatedly hit `unexpected token: ;` because they wrote
   `func f() = let x = a; let y = b; expr` without realizing that `=` body
   requires `let .. in ..` chains, not semicolons. Also add an explicit
   "no markdown fences" rule that was silently breaking ~14 runs across
   benchmarks where the model wrapped output in ` ```ailang `.

2. μRAG A/B (lang_harness × core × ailang, 90 runs each arm):
   - microrag=ON  → 97.4% adjusted pass rate
   - microrag=OFF → 90.0% adjusted pass rate
   - Δ = +7.4pp from μRAG, with `config_file_parser` and `cli_args`
     each gaining +50pp. μRAG should remain on by default.

3. M-EVAL-GAP-FIXES design doc (planned/v0_15_0/m-eval-gap-fixes.md)
   captures three follow-ups for v0.15.0:
   - M1 fold prompt change into next active prompt revision
   - M2 reproduce + fix the Pi `config_file_parser` regression (only Pi
     failure observed in v0.14.2; otherwise 0 API errors)
   - M3 either fix or document the match-arm-block parser corner case
     (already noted as a known bug in `.claude/rules/ailang-syntax.md`)

4. Eval-gap-finder script update (identify_python_only.sh): rewrite to
   handle the v0.14.x baseline schema (.id field, agent + standard runs,
   api_error filtering). Now reports per-mode (0-shot / +Repair / agent),
   per-harness, and surfaces "where does repair recover AILANG" as a
   prompt-improvement signal.

5. Axiom scorecard sync: `cmd/ailang/axiom_scorecard.json` now matches
   `docs/static/benchmarks/axiom_scorecard.json` for v0.14.2 (23/24).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Two unrelated CI failures blocking v0.15.0 release:

1. Hash drift on prompts/v0.12.1.md
   Commit 3465188 ("v0.14.2 eval-driven improvements") updated the root
   prompt to strengthen Rule #3 (=-body vs {}-body disambiguation) but
   did not update either the embedded copy at cmd/ailang/prompts/v0.12.1.md
   or the hash entries in the two versions.json files. Tests
   TestAILANGPromptLoading + TestPromptDisambiguation load via the registry
   and fail the hash check.
   Fix: sync embedded copy from root + bump hash to
   d45e0ae3096f012ad84a3a99e46da09a0fd6b984c837eecb3f4f381599cb5150 in both
   prompts/versions.json and cmd/ailang/prompts/versions.json.

2. Pipe-mode stderr leak
   The M-AGENT-MCP M5 fresh-fetch path always prints "note: prompt
   source=mcp version=latest sha=… (cache hit)" to stderr when there's an
   MCPNote, regardless of whether stdout is piped. Scripts capturing
   `ailang prompt | …` shouldn't have to filter benign info notes out of
   stderr. TestPromptCommand_Piping asserts no unexpected stderr.
   Fix: suppress the note when stdout is not a TTY (uses
   os.Stdout.Stat().Mode()&os.ModeCharDevice). AILANG_MCP_QUIET=1 still
   hard-suppresses; new AILANG_MCP_VERBOSE=1 forces the note even in pipe
   mode for operators who want it.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Follow-up from M-SMT-CROSS-MODULE-TYPES sprint-evaluator round-1
report (gap #3). The sprint added 221 lines to verify.go, pushing it
from 1028 (already over the 800-line limit) to 1249. Splitting now to
clear the violation.

- cmd/ailang/verify_filter.go (NEW, 446 lines): per-function filter
  helpers — buildNeededSortSet, filterRecordAliasesForFunction,
  filterExtraDeclarationsForFunction, filterADTTypesForFunction,
  collectSortSeeds + collectSortsFromType / collectSortsFromBody,
  extractBaseSortName, isPrimitiveSMTSort, isPrimitiveTypeName.
  Coherent unit: all the demand-driven filtering logic, no shared
  state with the verify command itself.
- cmd/ailang/verify_print.go (NEW, 128 lines): output formatting —
  printVerifyHuman + printVerifyJSON. Pure formatters, zero
  verification logic.
- cmd/ailang/verify.go (712 lines, was 1249): now contains only the
  verifyCommand entry point, AST extraction helpers, and the
  surrounding driver logic.

No functional change. All filter unit tests still pass, internal/smt
suite green, make lint clean. docparse re-verified post-split:
types/document.ail still 5/10, format_router.ail still 3/3, no
regressions.

Closes evaluator-flagged gap #3 from
.ailang/state/evaluations/eval_M-SMT-CROSS-MODULE-TYPES_round_1.json.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Round-1 sprint evaluation flagged three items (1 medium, 2 low). All three
addressed in this follow-up commit; no new design-doc deviations.

#1 (medium): Snapshot test for streaming-vs-non-streaming AI span shape
- New cmd/ailang/configdriven_streaming_span_snapshot_test.go (197 LOC)
- TestStreamingAISpan_SameShapeAsNonStreaming asserts that ctx.RecordAIEffect
  produces the same TraceEvent shape for "call" and "streamCall" — modulo
  OpName ("call" vs "streamCall") and Args content (1 vs 3 strings). Locks
  in the design-doc A4/A9 contract: streaming AI cannot silently degrade
  observability vs non-streaming AI.
- TestStreamingAISpan_RecordedFromAIStreamCallEndToEnd verifies the real
  aiStreamCall function reaches the recording call when invoked end-to-end
  against a mock SSE server. Belt-and-suspenders confirmation.

#2 (low): CapabilityNotSupported error code wiring
- Provider-registry misses (cmd/ailang/configdriven_streaming.go) now
  return ProtocolError("[ProviderNotFound] ...") rather than constructing
  a fake "ProviderNotFound" StreamErrorKind variant that wasn't in the
  declared ADT. Streaming-disabled / capabilities-streaming-false misses
  in BuildStreamRequest now carry "[CapabilityNotSupported]" prefix.
- Pattern: real StreamErrorKind variant + structured "[code]" prefix in
  the message string. Callers can pattern-match on ProtocolError AND
  switch on the [code] tag if needed. Documented inline.
- Tests updated to assert on (ProtocolError, [code] prefix) instead of
  fake-variant constructor names.

#3 (low): Recipe page pseudocode → concrete v1 snippet
- docs/docs/recipes/ai-token-streaming.md replaces the "pseudocode (v1.1
  will expose this via parseDelta)" block with a working v1 extractDelta
  template using std/json.decode and std/json.getString. Honest about the
  v1 limitation that std/json doesn't yet ship a path-walker — code shows
  the structural pattern callers should follow until v1.1's parseDelta.

All 6 packages still green: internal/pkg, internal/ai, internal/ai/configdriven,
internal/effects, internal/builtins, cmd/ailang. Full make test passes.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Examines where the multi-turn agent loop driver should live: upstream
in std/ai (extending runTools with hooks), downstream in motoko_agent
(custom loop calling step() directly), or whether motoko should
simplify its agent shape to fit the current runTools surface.

Triggered by motoko_agent PR #4 (the tool-loop migration follow-up to
PR #3) finding that rpc.ail's tool loop has 6 distinct decision points
upstream runTools doesn't model:
  1. Extension intercept dispatch (Accept/ContinueWithFeedback/...)
  2. Tool-call parser branching (NoToolCalls/ToolParseError/...)
  3. Tool gating policy (allowed/denied)
  4. Tool-handle routing (extension-handled tools)
  5. Native vs delegated backend split (ohmy_pi)
  6. Continuation-intent detection

Three options scored against the 12 axioms:
  A: motoko keeps custom loop calling step() directly (+1 net)
  B: extend upstream runTools with hook parameters (+6 net)
  C: motoko simplifies to fit current runTools shape (+3 net)
     — but with user-facing feature loss

Recommendation: HYBRID — Option A short-term to unblock PR #4
immediately, Option B long-term as M-AGENT-COMPOSABILITY using
motoko's prototype to inform the upstream hook design.

Includes the new mandatory Conflict Surface analysis (per the
design-doc gate added in this same release cycle) — Option B touches
public std/ai surface and adds 4 new ADTs that flow through the type
checker + iface layer.

Doc length: ~370 lines. Status: awaiting joint review by AILANG team
+ arni. Recommendation flips cleanly per 5 stated assumptions —
arni's input either confirms or rejects each one.

When a path dep's version changes since the last lockfile without a
matching upgrade-available message in the inbox, ailang lock now emits
a stderr warning pointing to 'ailang publish' as the correct path.

This catches the failure mode where editing [package].version directly
bypasses M-PKG-AUTONOMOUS-CASCADE-SAFE (msg 4a16ab61 issue #3).

Warning is best-effort: if the messaging store is unavailable the check
is skipped silently. Exit code stays 0 in all cases.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… 10 integration gaps

Today's live smoke testing of v0.18.0's M-MOTOKO-EXECUTOR-ADAPTER
surfaced 10 interconnected gaps that prevent trustworthy benchmark
numbers. Three got partial fixes during the day (HealthCheck no-spawn,
MOTOKO_REPO fallback, MOTOKO_HEADLESS, run_summary-before-done reorder)
but root causes remain across both repos. User feedback: "we need it
all I think. lets get to the bottom of the gaps - I think a design
doc process will help."

This sprint sequences the fixes properly:

  Phase 1: Investigation-first for gap #1 (run_summary not reaching
    disk on success path) — debug:checkpoint markers + bisect.
    Non-negotiable; writing a fix without the cause is gambling.

  Phase 2: motoko-side fixes (gap #1 root-cause fix + #6 extension
    visibility + #7 --headless flag + #8 --version mode + #10 TS
    process.exit removal so emission ordering doesn't matter)

  Phase 3: AILANG-side fixes (gap #2 success-criteria fallback to
    thinking.finish_reason + #5 MOTOKO_REPO discovery from wrapper)

  Phase 4: Cross-cutting (gap #4 session_id unification — adapter
    canonical, TS wrapper honors, AILANG runtime emits matching)

  Phase 5: Config layer (gap #3 + #9 cost_rates source-of-truth in
    models.yml.pricing → env-var override of motoko's profile config)

  Phase 6: End-to-end validation — TestEndToEnd_FullResultPopulation
    asserts every Result field; M5 paired-comparison
    motoko-claude-haiku-4-5 vs claude-haiku-4-5 produces real numbers.

Architectural posture: eliminate fragile assumptions at every layer.
Today's adapter assumes things that aren't true (wrapper preserves
session_id, cost_rates configured, run_summary always reaches disk,
loaded_extensions field accurate). After this hardening, none of those
assumptions remain — each replaced with explicit observable contracts.

Net axiom score: +13 (no hard violations). Strong A2 (replayability —
captured runs are fully reproducible), A7 (machines first — Result
fields mechanically reliable), A9 (cost visibility — eliminates $0
reporting gap).

Estimated 3 working days, ~530 LOC including tests, across both repos.
GATING for M5 of v0.18.0 (threshold-measurement) and v0.19.0
M-MOTOKO-EXT-PER-TASK (which needs accurate session_ids + extension
visibility from this hardening).

Cross-references:
- v0.18.0 M-MOTOKO-EXECUTOR-ADAPTER Future Work updated to point at
  this hardening as the trustworthy-numbers prerequisite
- v0.19.0 M-MOTOKO-EXT-PER-TASK Dependencies updated to mark v0.18.1
  as BLOCKING (was just "after local validation")

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…5a-c, gaps #3 #9)

Phase 5 of v0.18.1 hardening sprint. Closes gap #3 (CostUSD always 0
for motoko runs) and gap #9 (per-profile cost_rates duplication burden).

PRE-FIX STATE
=============
motoko's profile config required cost_rates for EVERY model used. Adding
a new model meant: (a) edit AILANG models.yml, (b) edit motoko's profile
config separately, (c) keep them in sync forever. The dogfood profile
shipped with no cost_rates for openrouter/anthropic models, so:

  - cost_warning + cost_exhausted events never fired
  - run_summary.total_cost_usd = 0
  - adapter Result.CostUSD = $0.000000 across every motoko-* model
  - eval-harness threshold-measurement experiments could not see cost

ARCHITECTURE
============
Single source of truth: AILANG models.yml. Per-task pricing flows:

  AILANG models.yml (input_per_1k, output_per_1k)
    → eval-harness constructs CostBudget(InputPer1K, OutputPer1K)
    → motoko adapter converts to per-1M millicents
    → MOTOKO_COST_INPUT_PER_1M_MILLICENTS / OUTPUT env vars
    → motoko load_cost_rates reads env first, profile config as fallback

The conversion: per_1k_usd × 1e8 = per_1m_millicents
  (×1000 for K→M, ×100 for $→¢, ×1000 for ¢→m¢)

motoko profiles can keep their cost_rates blocks for non-eval interactive
use; the env vars override per-task only when set.

M5a — Adapter env-var emit
==========================
internal/executor/motoko/motoko.go: when task.Budget != nil and rates
are >0, append both MOTOKO_COST_*_PER_1M_MILLICENTS env vars before the
spawn. Conversion is straight float×int — no rounding loss for typical
rates (a few cents per million tokens).

M5b — motoko-side env-var override
==================================
src/core/config.ail (motoko): new env_int helper + load_cost_rates now
declares ! {Env}. Reads MOTOKO_COST_INPUT_PER_1M_MILLICENTS first;
falls back to profile config json_int otherwise.

The ! {Env} effect change propagates one level (load_runtime_config in
config.ail already had ! {Env} from active_profile, so no caller-side
churn).

M5c — Tests
===========
Two new tests in internal/executor/motoko/execute_test.go:

  - TestExecute_BudgetEnvVarPassthrough: mock motoko writes received env
    vars to a side-channel file; test asserts both rates land at the
    expected per-1M millicent values for haiku-4-5 (25000/125000).

  - TestExecute_NoBudget_NoEnvVar: when task.Budget is nil (coordinator-
    driven runs, smoke runs that don't enforce budgets), the adapter
    must NOT emit the env vars. Defends the back-compat path.

M5d — Smoke wiring
==================
cmd/smoke-motoko/main.go: hardcode haiku-4-5 rates in Budget so the
smoke runner exercises the full pricing path. The eval harness derives
this from models.yml automatically.

KNOWN LIMITATION
================
End-to-end smoke verification is BLOCKED on a separate Bedrock validation
error: extensions register tools with names like "omnigraph/scaffold"
which fail Anthropic's ^[a-zA-Z0-9_-]{1,128}$ pattern. The cost path
WILL fire once that's fixed (handled in a separate ext-naming sprint).
The unit tests above prove the env-var plumbing is correct; the live
smoke needs the extension fix downstream.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…design docs

Phase 6 of v0.18.1 hardening sprint.

Moves both design docs from design_docs/planned/v0_18_1/ to
design_docs/implemented/v0_18_1/ and updates their status headers to
"Implemented (2026-05-08)" with cross-repo commit references.

Adds the v0.18.1 entry to changelogs/v0.10-current.md covering all
five phases:
  - Phase 1 (gap #1): JSONL drain race in TS layer
  - Phase 2 (gaps #6, #7, #8): extensions visibility, --headless, --version
  - Phase 3 (gaps #2, #5): success fallback, MOTOKO_REPO discovery
  - Phase 4 (gap #4): session_id unification
  - Phase 5 (gaps #3, #9): cost rates env-var passthrough

Acceptance gate: 5 of 7 conditions met; the remaining 2 (CostUSD>0
end-to-end + smoke success) blocked on a separate Bedrock validation
issue (extension tool names with `/` fail Anthropic's
^[a-zA-Z0-9_-]{1,128}$ pattern). The pricing env-var plumbing is
verified by unit tests; live smoke needs the extension fix downstream.

LOC tally: ~80 AILANG-side + ~250 motoko-side + 11 new tests across
both repos, in ~6 hours wall-clock vs the 3-day plan estimate.

Sprint retrospective: investigation-first paid off — the 12 debug:
checkpoint markers in Phase 1 directly identified the silent-exit
point as the TS process.exit-on-done race, which would have been
maddening to find by code-reading alone. The resulting fix was tiny
(~25 LOC across 2 TS files) but unblocked everything downstream.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

M-AILANG-ERROR-QUALITY iter 5 (compiler error-msg #3): the canonical_convergence
benchmark and several others trigger this when an LLM writes:

  pure func f() -> int =
    let x = a;          -- ← bug: `;` here is not valid
    rest

AILANG's `;` separator is only valid inside `{ ... }` block bodies; the
expression-body form (using `=` after the signature) chains `let` with
`let .. in ..`. Mixing the two is a parse error.

Previous error was generic: "unexpected token in expression: ;" + "This
token cannot start an expression". True but unactionable — the agent
doesn't know which valid form to switch to.

New PAR017 includes both valid forms verbatim, copy-pasteable:

  For expression body: pure func f() -> int = let x = 1 in let y = 2 in x + y
  For block body:      pure func f() -> int = { let x = 1; let y = 2; x + y }

Plus the "Pick ONE style per function" rule of thumb.

`;` is NEVER valid as the start of an expression so the hint is always
safe to emit when this token triggers PAR_NO_PREFIX_PARSE.

Live verification: `ailang check` on test file with `let total = 0;`
now emits PAR017 with all 3 hints + docs link. Build + full CI green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…oss-repo PR checklist v0.23.0 refresh

In-repo changes (the only M3 work that ships in this commit — the rest
lives in ailang-multivac):

1. cloudbuild-dev.yaml gains `build-agent-motoko` step mirroring
   `build-agent-go` (registry-cached buildx, FROMs agent-base via
   Dockerfile.agent-motoko's existing FROM). Push happens via
   `--push` flag like the other agent-* builders. `deploy-services`
   waitFor now includes build-agent-motoko so the deploy step doesn't
   race ahead of the image being available.

2. docker/agent-motoko-multivac-prs.md refreshed for v0.23.0 scope:
   - NEW: PR #0 (operational) — cloud `ailang-coordinator` is on a
     2026-04-28 image (pre-v0.21.0); MUST redeploy before E2E can
     exercise the v0.22.0 `requires` field
   - PR #2 addendum — coordinator agent config (config.yaml in the
     mounted ConfigMap) needs `motoko` agent entry with `worker_tags:
     [agent:motoko]` so M-COORD-MULTI-HOST-WORKERS tag matcher
     recognises the cloud Job as a valid dispatch target
   - PR #2 Job spec gets `max_retries = 1` (motoko is non-idempotent
     in cost — one retry max)
   - PR #3 (NEW, deferred) — `ailang-openrouter-api-key` prod secret
     resource. Currently only ailang-multivac-DEV has the secret;
     prod motoko cloud-dispatch is gated on cost analysis from dev
     throughput. Per-Job $0.30 cap on `motoko-or-gemma-4-26b` bounds
     the blast radius.
   - End-to-end smoke command updated to use the new --requires CLI
     flag from M2 (closes the v0.22.0 CLI gap that necessitated
     curl POST workarounds)

Acceptance gate refresh: 5 items, including the PR #0 pre-flight
("coordinator image timestamp shows post-v0.22.0 deploy").

What's NOT in this commit (intentional — cross-repo):
- The ailang-multivac terraform/cloud_run_jobs.tf addition (PR #2 body)
- The mounted coordinator config update (PR #2 addendum body)
- The prod secret resource (PR #3, deferred)
- The ailang-multivac cloudbuild.yaml + cloudbuild-images.yaml updates (PR #1)

Lints clean. cloudbuild-dev.yaml YAML validates (10 steps, build-agent-motoko
inserted between build-agent-go and push-coordinator).

Refs: M-COORD-MULTI-HOST-WORKERS Future Work item #1 (cloud-fallback
routing) — the local-side closures landed in M1/M2; this completes the
in-repo half of the cross-repo cloud-side work.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>