space-architect 9.6.0 → 9.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d95b9e18cb5c8dbaf32c57ad55915e12b387ee5a68eb5cea89e52c0ab3a2542
-  data.tar.gz: d95ef73a8929c852f58c8712f7dfce3bd14eab18e06c0e518f8bdd6c55625588
+  metadata.gz: f12c744b4e442b1ba96e09e2ede78bf7f048932d61bd891c667b65f62c78674a
+  data.tar.gz: 87e62449c0d0539fdf688fc7faa43909cbc0dc034c5a0ee477b645f3ceac7a9e
 SHA512:
-  metadata.gz: 1e36ea6062b43c49d1ebcf69fac6205af9e7f24cb5e51bff1d2ae70db518ef07facafa41d17e8bb7de2736d8748b84ab97d42a7ce70513046b7b089c4ff1d2cc
-  data.tar.gz: 659816b4ea7286f5a24fb8ff16d0e0eb2783258051ceddeab53f00ba8e2e3ea9adfbcd1150132d751a5fd4f0531070689796a3c01135f2e49c04faa5c7c51224
+  metadata.gz: c84129b96fa520324e1c15bf00f8f3de595bc642248ce3e72c9af0283b9802f63d2d3e7a15f1c450321bdf6c9840513ecce5cac477adf33cd0a8528bd63d585f
+  data.tar.gz: f1fff1968103fd8108619aefbcfd69531c6f2c916c42c4748ea75247ef8bf208d850a3c6bc79b208f12eb1c35b0cb9fc906a10455a357e13cd8ef1c326dec656

data/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.7.0] - 2026-10-30
+
+### Added
+
+- **Structured-record emission (I16)** — the loop commands now mirror the
+  iteration record to a space-server as structured data: `architect
+  freeze`/`verdict`/`integrate` and lane completion POST to the four ingest
+  mouths (`/iterations/ingest/{freeze,lane,verdict,integration}`). Payloads
+  derive from the canonical sources (the iteration file, space.yaml lane
+  records, gate sidecars); the verdict detail rides a new fenced ` ```rulings `
+  YAML block (ac_rulings + phase0_resolutions) in the `## Verdict` body.
+  Config: `~/.config/space-architect/emission.yaml` (host/token/disabled),
+  session-sink semantics — unconfigured is fully inert, ENV overrides per
+  field (`SPACE_ARCHITECT_EMISSION_HOST/_TOKEN/_DISABLED`), best-effort
+  POSTs that never raise into or block a loop command. `architect emit`
+  replays the emission byte-stable.
+
 ## [9.6.0] - 2026-10-17
 
 ### Changed

data/lib/space_architect/architect_project.rb

@@ -2,6 +2,7 @@
 
 require "yaml"
 require "erb"
+require "json"
 require "open3"
 require "fileutils"
 require "pathname"
@@ -92,8 +93,23 @@ module Space::Architect
       }
     JSON
 
-    def initialize(space:)
+    def initialize(space:, emitter: nil)
       @space = space
+      # I16: the emission sink — an injected emitter (tests) always wins;
+      # the default resolves the emission config lazily, once per instance,
+      # and memoizes. nil resolution = unconfigured = every call site no-ops.
+      @injected_emitter = emitter unless emitter.nil?
+    end
+
+    # The resolved emitter for this space, or nil when unconfigured (no file,
+    # missing host/token, or disabled — Space::Architect::IterationEmission).
+    # Memoized on the first call-site resolution so machine state cannot
+    # differ between the five hooks of one command invocation.
+    def emitter
+      return @injected_emitter if instance_variable_defined?(:@injected_emitter)
+      return @resolved_emitter if instance_variable_defined?(:@resolved_emitter)
+
+      @resolved_emitter = IterationEmission.emitter_for(space)
     end
 
     def init!(message: nil)
@@ -261,6 +277,17 @@ module Space::Architect
       git_run("-C", space.path.to_s, "commit", "-m",
         compose_message("I#{nn} freeze:", "I#{nn}: record freeze sha", message), "--", Space::Core::Space::METADATA_FILE)
 
+      # I16 emission — mouth 1 (freeze): identity + the frozen gates, derived
+      # from the just-committed text. The already-frozen early return above
+      # emits nothing. Best-effort: unconfigured no-ops, failures never block.
+      safe_emit("freeze #{iteration}") do
+        em = emitter
+        next unless em
+        em.post("freeze", IterationEmission.build_freeze(
+          ordinal: entry["ordinal"], name: entry["name"], freeze_sha: sha,
+          branch: head_branch, gates: parse_gates(text)))
+      end
+
       sha
     end
 
@@ -352,6 +379,18 @@ module Space::Architect
         compose_message("I#{nn} verdict:", "I#{nn}: verdict", message), "--", rel, Space::Core::Space::METADATA_FILE)
 
       head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
+
+      # I16 emission — mouth 3 (verdict): the decision plus ac_rulings /
+      # phase0_resolutions parsed from the body's ```rulings block when one is
+      # present. The body lands in the markdown verbatim either way.
+      safe_emit("verdict #{iteration}") do
+        em = emitter
+        next unless em
+        em.post("verdict", IterationEmission.build_verdict(
+          ordinal: entry["ordinal"], name: entry["name"], decision: decision,
+          rulings: IterationEmission.parse_rulings(body)))
+      end
+
       { decision: decision, sha: head.strip }
     end
 
@@ -387,6 +426,12 @@ module Space::Architect
         compose_message("I#{nn} evidence:", "I#{nn}: evidence", message), "--", rel)
       head, = git_capture("-C", space.path.to_s, "rev-parse", "HEAD")
 
+      # I16 emission — mouth 2 (lane): the lane's disposition scalars from the
+      # space.yaml record, status "complete". With lane nil, only when the
+      # entry records exactly ONE lane (the single-lane iteration shorthand);
+      # a multi-lane unlabeled run has no single owner — skip.
+      emit_lane_complete!(iteration, entry, lane)
+
       status_line = raw.lines.reverse_each.find { |l| l.strip.start_with?("STATUS:") }&.strip
       { sha: head.strip, lines: raw.lines.count, status_line: status_line, lane: lane }
     end
@@ -408,6 +453,149 @@ module Space::Architect
       section_body(text, "## Acceptance Criteria")
     end
 
+    # I16 S4 — `architect emit`: re-derive the emission payloads for one facet
+    # from the canonical sources (space.yaml, the frozen iteration file via
+    # `git show`, the gate sidecars) through the EXACT builders the live hook
+    # call sites use, so a re-send replays the same bytes. Returns the array
+    # of payloads for the facet — empty for "nothing to emit". Deliberately
+    # single-iteration: no bulk backfill surface, no enumeration of
+    # historical I*.md files.
+    def emission_replays(iteration, facet:, lane: nil)
+      entry = slice_entry(iteration)
+      case facet
+      when "freeze"      then freeze_replay(entry)
+      when "lane"        then lane_replays(entry, lane)
+      when "verdict"     then verdict_replay(entry)
+      when "integration" then integration_replay(entry)
+      else raise Space::Core::Error, "unknown facet '#{facet}' — one of: freeze, lane, verdict, integration"
+      end
+    end
+
+    # freeze facet: gates re-parsed from the frozen file's byte state (same
+    # parse_gates path as the live freeze), branch re-read live — identical
+    # whenever the space repo's HEAD branch hasn't changed since the freeze.
+    def freeze_replay(entry)
+      sha = entry["freeze_sha"]
+      return [] unless sha
+
+      text, _, st = git_capture("-C", space.path.to_s, "show", "#{sha}:#{entry['file']}")
+      raise Space::Core::Error, "could not read #{entry['file']} at freeze #{sha[0, 8]}" unless st.success?
+
+      [IterationEmission.build_freeze(
+        ordinal: entry["ordinal"], name: entry["name"], freeze_sha: sha,
+        branch: head_branch, gates: parse_gates(text))]
+    end
+
+    # lane facet: the space.yaml lane records (or --lane NAME). When the lane
+    # has a gate sidecar, replay the gate-results shape (scalars minus status
+    # + gate_results re-attached from the sidecar, transcript from the sibling
+    # .md) — the live gate-time payload; otherwise the completion shape
+    # (status "complete") — the live evidence-time payload.
+    def lane_replays(entry, lane)
+      lanes = entry["lanes"] || []
+      if lane
+        lanes = lanes.select { |l| l["name"] == lane }
+        raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{entry['name']}'" if lanes.empty?
+      end
+
+      lanes.map do |record|
+        sidecar = newest_lane_sidecar(record["name"])
+        if sidecar
+          IterationEmission.build_lane(ordinal: entry["ordinal"], name: entry["name"],
+            lane_record: record, gate_results: lane_sidecar_results(sidecar))
+        else
+          IterationEmission.build_lane(ordinal: entry["ordinal"], name: entry["name"],
+            lane_record: record, status: "complete")
+        end
+      end
+    end
+
+    # verdict facet: the entry's recorded decision + the current iteration
+    # file's Verdict section ```rulings block (the section the live verdict
+    # command wrote — post-freeze, so it is read from the working tree).
+    def verdict_replay(entry)
+      decision = entry["verdict"]
+      return [] if decision.nil? || decision == "pending"
+
+      path = space.path.join(entry["file"])
+      raise Space::Core::Error, "#{entry['file']} does not exist" unless path.exist?
+
+      [IterationEmission.build_verdict(ordinal: entry["ordinal"], name: entry["name"],
+        decision: decision,
+        rulings: IterationEmission.parse_rulings(section_body(path.read, "## Verdict").to_s))]
+    end
+
+    # integration facet: the lanes' recorded integrate_sha/integration_branch
+    # plus the project integration branch. "nothing to emit" ([]) when no lane
+    # has merge data.
+    def integration_replay(entry)
+      lanes = (entry["lanes"] || []).select { |l| l["integrate_sha"] }
+      return [] if lanes.empty?
+
+      branch = lanes.filter_map { |l| l["integration_branch"] }.first || project_integration_branch
+      merge_commits = lane_merge_commits(lanes, branch)
+      [IterationEmission.build_integration(
+        ordinal: entry["ordinal"], name: entry["name"], branch: branch,
+        lanes: lanes.map { |l|
+          { name: l["name"], merge_sha: merge_commits[l["name"]] || l["integrate_sha"],
+            integration_branch: l["integration_branch"] }
+        })]
+    end
+
+    # The live integration emission carries each lane's repo MERGE commit (the
+    # tip after its --no-ff merge); space.yaml records the lane WORKTREE commit
+    # (integrate_sha). The merge commit is derivable from the canonical repo
+    # history — each merge's second parent is exactly the lane branch tip — so
+    # the re-send replays the same merge_sha the live path posted. When the
+    # branch history no longer holds the merge (rewritten/deleted), the
+    # recorded integrate_sha is the only remaining truth and is used as-is.
+    def lane_merge_commits(lanes, branch)
+      lanes.group_by { |l| l["repo"] }.flat_map do |repo, group|
+        next [] unless repo
+        out, _, st = git_capture("-C", space.path.join("repos", repo).to_s,
+          "rev-list", "--merges", "--parents", branch)
+        next [] unless st.success?
+        group.filter_map do |l|
+          next unless l["integrate_sha"]
+          commit = out.strip.split("\n")
+                       .find { |line| line.split.drop(1).include?(l["integrate_sha"]) }
+                       &.split
+                       &.first
+          commit ? [l["name"], commit] : nil
+        end
+      end.to_h
+    end
+
+    # The newest lane gate sidecar in build/gate/ whose sibling .md transcript
+    # names the lane: sidecar files are keyed to their .md by basename, and
+    # the .md's "Lane: <name> (…}" header line is the only recorded lane
+    # association. Filenames embed a monotonic timestamp — reverse sort is
+    # newest-first.
+    def newest_lane_sidecar(lane_name)
+      dir = space.path.join("build", "gate")
+      return nil unless dir.exist?
+
+      # paths:exempt - the .extname == ".json" filter structurally cannot match a dotfile-prefixed name (".json" has no extname), so raw enumeration of the build/gate scratch dir is already dotfile-safe here
+      candidates = dir.children.select { |f| f.extname == ".json" }.sort_by(&:to_s).reverse
+      candidates.find do |sidecar|
+        md = sidecar.sub_ext(".md")
+        md.exist? && File.foreach(md).any? { |line| line.start_with?("Lane: #{lane_name} (") }
+      end
+    end
+
+    # Re-attach gate_results from a sidecar: same entry shape the live
+    # gate-time lane emission built (reason omitted when empty — the server
+    # stores NULL for ""), transcript from the sibling .md.
+    def lane_sidecar_results(sidecar)
+      transcript = sidecar.sub_ext(".md").read
+      JSON.parse(sidecar.read).map do |r|
+        IterationEmission.map_gate_result(
+          { gate_id: r["gate_id"], status: r["status"], reason: r["reason"] },
+          transcript)
+      end
+    end
+
+
     # Integrate ONE architect-judged-passing lane: commit the builder's working tree on
     # the lane branch, then merge --no-ff into the repo's lane/<id> integration branch.
     # Runs NO gates and makes NO pass/fail decision. Refuses a mechanically-failing lane
@@ -534,6 +722,14 @@ module Space::Architect
         raise Space::Core::Error, "Integrated #{done.empty? ? "(none)" : done} then stopped at '#{lane}': #{e.message}"
       end
 
+      # I16 emission — mouth 4 (integration): one integration POST, then a
+      # per-merged-lane lane-mouth scalar re-emission re-sliced from space.yaml
+      # AFTER the merge mutations (a bounds override accepted at integrate
+      # time must land in the record). Teardown-only calls never reach this —
+      # they early-return above. Emission happens before teardown so a
+      # teardown failure can never cost an already-merged lane its record.
+      emit_integration!(iteration, merged)
+
       teardown_lanes!(iteration, merged, force: force) if teardown
       merged
     ensure
@@ -575,7 +771,9 @@ module Space::Architect
     # #run_gates, the only intended caller shape. Returns the path.
     def gate_transcript(iteration, gate_results, lane: nil, now: Time.now)
       entry, base_dir, repo = resolve_gate_run(iteration, lane)
-      write_transcript(:gate, entry, repo, base_dir, lane, gate_results, nil, now)
+      path = write_transcript(:gate, entry, repo, base_dir, lane, gate_results, nil, now)
+      emit_lane_gate_results!(entry, lane, path, gate_results) if lane
+      path
     end
 
     # Rehearse the DRAFTED gates in the WORKING-TREE iteration file — before the
@@ -1074,6 +1272,103 @@ module Space::Architect
       body.empty? ? composed : "#{composed}\n\n#{body}"
     end
 
+    # The emission belt: a payload-build or call-site bug must never change a
+    # loop command's exit code, stdout, or commit behavior — exactly one
+    # stderr line, then the command carries on. (Emitter#post itself never
+    # raises; this belt guards the payload construction around it.)
+    def safe_emit(context)
+      yield
+    rescue Exception => e # belt, by contract — even a NoMemoryError must not kill the loop
+      $stderr.puts "emission skipped (#{context}): #{e.class}: #{e.message.to_s[0, 200]}"
+    end
+
+    # I16 emission — mouth 2 (lane): the lane's disposition scalars from the
+    # space.yaml record, status "complete". With lane nil, only when the
+    # entry records exactly ONE lane (the single-lane iteration shorthand);
+    # a multi-lane unlabeled run has no single owner — skip.
+    def emit_lane_complete!(iteration, entry, lane)
+      lane_name = lane
+      unless lane_name
+        lanes = entry["lanes"] || []
+        lane_name = lanes.first["name"] if lanes.one?
+      end
+      return unless lane_name
+
+      safe_emit("lane complete #{lane_name}") do
+        em = emitter
+        next unless em
+        record = (slice_entry(iteration)["lanes"] || []).find { |l| l["name"] == lane_name }
+        next unless record
+        em.post("lane", IterationEmission.build_lane(
+          ordinal: entry["ordinal"], name: entry["name"], lane_record: record, status: "complete"))
+      end
+    end
+
+    # I16: the structured sidecar — a JSON mirror of the executed gates
+    # (gate_id/status/reason/stdout/stderr/exit_code/cmd/dir) written beside
+    # the transcript .md (same basename; additive — the .md stays
+    # byte-unchanged). Lane runs only: unlabeled gate runs emit nothing, and
+    # `architect emit` re-attaches gate_results from the newest sidecar whose
+    # sibling .md names the lane.
+    def write_gate_sidecar(transcript_path, gate_results)
+      safe_emit("gate sidecar #{transcript_path.basename}") do
+        sidecar = transcript_path.sub_ext(".json")
+        sidecar.write(JSON.generate(gate_results.map { |g| IterationEmission.map_sidecar_gate(g) }))
+      end
+    end
+
+    # I16 emission — mouth 2 (lane), gate-results shape: the same scalars as
+    # the completion shape MINUS status, plus one gate_results entry per gate
+    # ({gate_id, status exactly "pass"/"fail", reason omitted when empty,
+    # transcript = the .md content just written}). Only called for lane runs.
+    def emit_lane_gate_results!(entry, lane, transcript_path, gate_results)
+      write_gate_sidecar(transcript_path, gate_results)
+      safe_emit("lane gate results #{lane}") do
+        em = emitter
+        next unless em
+        record = (entry["lanes"] || []).find { |l| l["name"] == lane }
+        next unless record
+        transcript = transcript_path.read
+        em.post("lane", IterationEmission.build_lane(
+          ordinal: entry["ordinal"], name: entry["name"], lane_record: record,
+          gate_results: gate_results.map { |g|
+            IterationEmission.map_gate_result({ gate_id: g[:id], status: g[:status], reason: g[:reason] }, transcript)
+          }))
+      end
+    end
+
+    # I16 emission — mouth 4 (integration): one integration POST, then a
+    # per-merged-lane lane-mouth scalar re-emission re-sliced from space.yaml
+    # AFTER the merge mutations (a bounds override accepted at integrate time
+    # must land in the record). Emission happens before teardown so a teardown
+    # failure can never cost an already-merged lane its record.
+    def emit_integration!(iteration, merged)
+      safe_emit("integration #{iteration}") do
+        em = emitter
+        next unless em
+        fresh = slice_entry(iteration)
+        em.post("integration", IterationEmission.build_integration(
+          ordinal: fresh["ordinal"], name: fresh["name"],
+          branch: merged.first[:integration_branch],
+          lanes: merged.map { |m|
+            { name: m[:lane], merge_sha: m[:merge_sha], integration_branch: m[:integration_branch] }
+          }))
+        (fresh["lanes"] || []).each do |l|
+          next unless merged.any? { |m| m[:lane] == l["name"] }
+          em.post("lane", IterationEmission.build_lane(
+            ordinal: fresh["ordinal"], name: fresh["name"], lane_record: l, status: "integrated"))
+        end
+      end
+    end
+
+    # The space repo's HEAD branch, nil when detached (git abbrev-ref prints
+    # "HEAD" there; a real branch of that name is not a thing git creates).
+    def head_branch
+      out, = git_capture("-C", space.path.to_s, "rev-parse", "--abbrev-ref", "HEAD")
+      branch = out.strip
+      branch unless branch == "HEAD"
+    end
+
     # integrate!'s own space.yaml commit, by pathspec — like record_verdict!'s sweep, so
     # other uncommitted work in the space isn't pulled in. A call that mutated nothing
     # (teardown-only over lanes with no worktree, or a call that raised before touching

data/lib/space_architect/cli/architect.rb

@@ -847,6 +847,60 @@ module Space::Architect
         end
       end
 
+      # I16: re-send the structured iteration emissions for ONE iteration —
+      # payloads re-derived from the canonical sources through the exact
+      # builders the live hook call sites use, so a replay is byte-identical
+      # to what the loop sent. Deliberately single-iteration: no bulk
+      # backfill surface, no enumeration of historical I*.md files.
+      class Emit < BaseCommand
+        desc "Re-send the structured emissions for one iteration (freeze/lane/verdict/integration; idempotent replay)"
+        phase 53, "Project"
+        argument :iteration, required: true,  desc: "Iteration name"
+        argument :space,     required: false, desc: "Space identifier (default: $PWD)"
+        option :facet, default: "all", desc: "Which facet to emit: freeze, lane, verdict, integration, or all (default)"
+        option :lane,  default: nil,   desc: "Lane name filter (lane facet only; default: all recorded lanes)"
+
+        FACETS = %w[freeze lane verdict integration].freeze
+
+        def call(iteration:, space: nil, facet: "all", lane: nil, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            requested = facet == "all" ? FACETS : FACETS & [facet]
+            if requested.empty?
+              raise Space::Core::Error,
+                "unknown facet '#{facet}' — one of: #{(FACETS + ["all"]).join(', ')}"
+            end
+
+            render(store.find(space)) do |sp|
+              project = ArchitectProject.new(space: sp)
+              emitter = IterationEmission.emitter_for(sp)
+              failed = false
+              requested.each do |f|
+                payloads = project.emission_replays(iteration, facet: f, lane: lane)
+                if payloads.empty?
+                  terminal.say "nothing to emit (#{f})"
+                  next
+                end
+                payloads.each do |payload|
+                  unless emitter
+                    terminal.say "emission off (unconfigured)"
+                    next
+                  end
+                  res = emitter.post(f, payload)
+                  if res
+                    terminal.say "emitted #{f} → #{res[:status]}"
+                  else
+                    failed = true
+                    terminal.say "emission failed (#{f}) — see stderr"
+                  end
+                end
+              end
+              CLI.record_outcome(Outcome.new(exit_code: failed ? 1 : 0))
+            end
+          end
+        end
+      end
+
       # Pretty-print a pi agent run.jsonl as it streams — the ported runlog
       # printer. No space resolution: the stream is the whole input.
       class Runlog < BaseCommand
@@ -1440,6 +1494,7 @@ Space::Architect::CLI::Registry.register "install-extensions", Space::Architect:
 Space::Architect::CLI::Registry.register "install-agents",   Space::Architect::CLI::Architect::InstallAgents
 Space::Architect::CLI::Registry.register "runlog",          Space::Architect::CLI::Architect::Runlog
 Space::Architect::CLI::Registry.register "looplog",         Space::Architect::CLI::Architect::Looplog
+Space::Architect::CLI::Registry.register "emit",           Space::Architect::CLI::Architect::Emit
 Space::Architect::CLI::Registry.register "bug-report",     Space::Architect::CLI::Architect::BugReport
 Space::Architect::CLI::Registry.register "cost",           Space::Architect::CLI::Architect::Cost
 Space::Architect::CLI::Registry.register "brief" do |b|

data/lib/space_architect/iteration_emission.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "json"
+require "yaml"
+require "pathname"
+
+module Space::Architect
+  # I16 — the structured-record emission layer: config resolution (session-sink
+  # mirror: unconfigured = fully inert, configured = capture on, mute knob
+  # available), the best-effort Net::HTTP client, the payload builders that
+  # derive from the canonical sources the loop commands already hold, and the
+  # ```rulings block parser. ArchitectProject's five hook call sites guard
+  # through `emitter&.post` inside a rescue-all belt; nothing here may ever
+  # raise into a loop command or change its exit code, stdout, or commits.
+  module IterationEmission
+    # Frozen tuning (mirrors the spec; session-sink pins its own constants the
+    # same way): per attempt 2s open / 5s read, at most 2 attempts, retry on
+    # network errors or 5xx ONLY — 4xx is never retried.
+    OPEN_TIMEOUT = 2
+    READ_TIMEOUT = 5
+    MAX_ATTEMPTS = 2
+
+    # The four server mouths (I15, frozen): POST <host>/iterations/ingest/<mouth>.
+    MOUTHS = %w[freeze lane verdict integration].freeze
+
+    # Iteration/lane status vocabularies (frozen): nothing else is emitted.
+    ITERATION_STATUSES = %w[frozen integrated].freeze
+    LANE_STATUSES      = %w[complete integrated].freeze
+
+    # The space-slug rule (architect_project.rb :1642), with the emission-layer
+    # fallback: space.data["id"] when the title is absent or slugifies empty.
+    def self.slug_for(space)
+      slug = space.title.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+      slug.empty? ? space.data["id"].to_s : slug
+    rescue StandardError
+      space.data["id"].to_s
+    end
+
+    # ---- config resolution (the Routing.global_path pattern) ---------------
+
+    # Global file ~/.config/space-architect/emission.yaml, path overridable via
+    # SPACE_ARCHITECT_EMISSION_GLOBAL_CONFIG — exactly Routing.global_path's
+    # shape (env pin first, else the ~/.config path; parity outranks XDG).
+    def self.global_path(env: ENV)
+      override = env["SPACE_ARCHITECT_EMISSION_GLOBAL_CONFIG"]
+      return Pathname.new(override) unless override.nil?
+
+      Pathname.new("~/.config/space-architect/emission.yaml").expand_path
+    end
+
+    # Resolve the configured Emitter for a space, or nil when unconfigured:
+    # no file, missing host/token, or disabled. ENV beats the file per field,
+    # both ways: SPACE_ARCHITECT_EMISSION_HOST / _TOKEN override their file
+    # values; _DISABLED ("1"/"true" mutes; any other present value unmutes)
+    # overrides the file's disabled knob in both directions. A malformed or
+    # unreadable file is INERT PLUS one stderr line naming the path and the
+    # problem; an absent file is inert and silent (a no-config machine is a
+    # normal state — zero output, zero network).
+    def self.emitter_for(space, env: ENV, err: $stderr)
+      config = read_config(global_path(env: env), err: err)
+      disabled_env = env["SPACE_ARCHITECT_EMISSION_DISABLED"]
+      host   = env["SPACE_ARCHITECT_EMISSION_HOST"]   || config&.[](:host)
+      token  = env["SPACE_ARCHITECT_EMISSION_TOKEN"]  || config&.[](:token)
+      disabled =
+        if disabled_env.nil?
+          config&.[](:disabled) == true
+        else
+          %w[1 true].include?(disabled_env.strip.downcase)
+        end
+
+      return nil if disabled || host.to_s.strip.empty? || token.to_s.strip.empty?
+
+      Emitter.new(host: host.to_s.strip, token: token.to_s, slug: slug_for(space))
+    end
+
+    def self.read_config(path, err:)
+      return nil unless File.file?(path.to_s)
+
+      doc = YAML.safe_load(File.read(path.to_s), aliases: true)
+      unless doc.is_a?(Hash)
+        err.puts "emission config (#{path}): expected a YAML mapping, got #{doc.inspect} — file config ignored"
+        return nil
+      end
+      {
+        host: doc["host"], token: doc["token"], disabled: doc["disabled"] == true
+      }
+    rescue Psych::Exception => e
+      err.puts "emission config (#{path}): malformed YAML — #{e.message} — file config ignored"
+      nil
+    rescue StandardError => e
+      err.puts "emission config (#{path}): unreadable — #{e.class}: #{e.message} — file config ignored"
+      nil
+    end
+
+    # ---- the client ---------------------------------------------------------
+
+    # One best-effort POST per call to <host>/iterations/ingest/<mouth>.
+    # NEVER raises into the caller: at most MAX_ATTEMPTS attempts (retry on
+    # network errors or 5xx only), then exactly one stderr line — the mouth
+    # path plus the failure class/status with a bounded response excerpt.
+    # Never the token, never the payload. On 2xx returns
+    # {status:, body:} (body JSON-parsed when possible).
+    class Emitter
+      attr_reader :host, :token, :slug
+
+      def initialize(host:, token:, slug:)
+        @host   = host.sub(%r{/+\z}, "") # trailing slashes stripped once
+        @token  = token
+        @slug   = slug
+      end
+
+      def post(mouth, payload)
+        path = "/iterations/ingest/#{mouth}"
+        body = JSON.generate(payload)
+        response = nil
+        last_error = nil
+        MAX_ATTEMPTS.times do
+          begin
+            response, last_error = post_once(path, body)
+          rescue *NETWORK_ERRORS => e
+            last_error = e # network failure: fall through to the retry
+          end
+          break if response && response.code.to_i.between?(200, 499)
+          # 5xx and network failures fall through to the retry; 4xx breaks —
+          # never retried.
+        end
+
+        return result_for(response) if response&.code.to_i.between?(200, 299)
+
+        report_failure(path, response, last_error)
+        nil
+      end
+
+      private
+
+      def post_once(path, body)
+        uri = URI.parse("#{@host}#{path}")
+        uri.scheme ||= "http"
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = OPEN_TIMEOUT
+        http.read_timeout = READ_TIMEOUT
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = "Bearer #{@token}"
+        request["X-Space-Slug"] = @slug
+        request.body = body
+        response = http.request(request)
+        [response, nil]
+      end
+
+      NETWORK_ERRORS = [
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH,
+        Errno::EPIPE, Errno::EACCES, Errno::EADDRNOTAVAIL, Errno::ETIMEDOUT,
+        SocketError, IOError, EOFError, SystemCallError,
+        Net::OpenTimeout, Net::ReadTimeout, Net::HTTPBadResponse,
+        OpenSSL::SSL::SSLError, Timeout::Error
+      ].freeze
+
+      def result_for(response)
+        { status: response.code.to_i, body: safe_parse(response.body) }
+      end
+
+      def safe_parse(raw)
+        JSON.parse(raw.to_s)
+      rescue JSON::ParserError, ArgumentError
+        raw.to_s
+      end
+
+      # One stderr line: mouth path + failure class/status + bounded response
+      # excerpt when one arrived. The token lives only in the Authorization
+      # header; the payload is never echoed; a response body is server-written
+      # text and never echoes either.
+      def report_failure(path, response, last_error)
+        detail =
+          if response
+            "status #{response.code} — #{response.body.to_s[0, 200]}"
+          else
+            "#{last_error&.class || 'network failure'}"
+          end
+        $stderr.puts "#{path}: emission failed after #{MAX_ATTEMPTS} attempt(s): #{detail}"
+      end
+    end
+
+    # ---- payload builders (contract keys only; nil/empty scalars omitted) --
+    #
+    # The server's frozen contracts (repos/all-fax-no-printer
+    # app/contracts/ingest_iteration_*.rb) 422 unknown keys and empty `expect`
+    # maps — builders emit ONLY contract keys and omit `expect` ENTIRELY when
+    # the gate declares none (never {}).
+
+    def self.compact_scalars(hash)
+      hash.reject { |_k, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+    end
+
+    # One gate as the freeze mouth stores it: id/ac/cmd/cwd/timeout/expect,
+    # nil fields omitted, expect dropped entirely when absent or empty.
+    def self.map_gate(g)
+      g = g.transform_keys(&:to_s)
+      compact_scalars(
+        "id" => g["id"], "ac" => g["ac"], "cmd" => g["cmd"], "cwd" => g["cwd"],
+        "timeout" => g["timeout"], "expect" => (g["expect"].is_a?(Hash) && !g["expect"].empty? ? g["expect"] : nil)
+      )
+    end
+
+    def self.build_freeze(ordinal:, name:, freeze_sha:, branch:, gates:)
+      compact_scalars(
+        "iteration" => compact_scalars(
+          "ordinal" => ordinal, "name" => name, "freeze_sha" => freeze_sha,
+          "branch" => branch, "status" => "frozen"
+        ),
+        "gates" => Array(gates).map { |g| map_gate(g) }
+      )
+    end
+
+    # Lane-mouth scalars as stored in the space.yaml lane record, re-sliced
+    # from it — never a hand-maintained copy. status/gate_results ride when
+    # given (nil/empty omitted; an absent key leaves stored rows untouched).
+    def self.build_lane(ordinal:, name:, lane_record:, status: nil, gate_results: nil)
+      r = lane_record.transform_keys(&:to_s)
+      lane = compact_scalars(
+        "name" => r["name"], "repo" => r["repo"], "base_sha" => r["base_sha"],
+        "model" => r["model"], "harness" => r["harness"], "effort" => r["effort"],
+        "touch_set" => (Array(r["touch_set"]) unless Array(r["touch_set"]).empty?),
+        "bounds_override_reason" => r["bounds_override_reason"],
+        "status" => status,
+        "gate_results" => gate_results
+      )
+      { "iteration" => compact_scalars("ordinal" => ordinal, "name" => name), "lane" => lane }
+    end
+
+    def self.map_gate_result(g, transcript)
+      result = compact_scalars(
+        "gate_id" => g[:gate_id], "status" => g[:status].to_s,
+        "reason" => g[:reason].to_s, "transcript" => transcript
+      )
+      result.delete("reason") if g[:reason].to_s.empty?
+      result
+    end
+
+    # A gate transcript sidecar entry: the structured mirror of one executed
+    # gate (all keys always present — it is the faithful machine mirror).
+    def self.map_sidecar_gate(g)
+      {
+        "gate_id" => g[:id].to_s, "status" => g[:status].to_s, "reason" => g[:reason].to_s,
+        "stdout" => g[:stdout].to_s, "stderr" => g[:stderr].to_s,
+        "exit_code" => g[:exit_code], "cmd" => g[:cmd].to_s, "dir" => g[:dir].to_s
+      }
+    end
+
+    def self.build_verdict(ordinal:, name:, decision:, rulings:)
+      verdict = compact_scalars(
+        "decision" => decision,
+        "ac_rulings" => (rulings[:ac_rulings] if rulings[:ac_rulings]&.any?),
+        "phase0_resolutions" => (rulings[:phase0_resolutions] if rulings[:phase0_resolutions]&.any?)
+      )
+      { "iteration" => compact_scalars("ordinal" => ordinal, "name" => name), "verdict" => verdict }
+    end
+
+    def self.build_integration(ordinal:, name:, branch:, lanes:)
+      {
+        "iteration" => compact_scalars("ordinal" => ordinal, "name" => name, "status" => "integrated"),
+        "integration" => {
+          "branch" => branch,
+          "lanes" => lanes.map { |l| compact_scalars("name" => l[:name], "merge_sha" => l[:merge_sha], "integration_branch" => l[:integration_branch]) }
+        }
+      }
+    end
+
+    # ---- the ```rulings block (S3) ------------------------------------------
+    #
+    # A fenced YAML block inside the ## Verdict body — the ```gates/```lanes
+    # discipline applied to verdict detail. Valid entries ride the emission
+    # verbatim; ANY invalid entry is dropped with one loud stderr line naming
+    # it; a malformed block (bad YAML, wrong shape) is dropped with one line;
+    # no block at all is silent decision-only. Extraction never raises.
+
+    def self.parse_rulings(body, err: $stderr)
+      match = body.to_s.match(/^```rulings\n(.*?)^```/m)
+      return {} unless match
+
+      doc = YAML.safe_load(match[1], aliases: true)
+      unless doc.is_a?(Hash)
+        err.puts "rulings block: expected a YAML mapping, got #{doc.inspect} — dropped (decision-only emission)"
+        return {}
+      end
+
+      {
+        ac_rulings: valid_rulings(Array(doc["ac_rulings"]), err: err),
+        phase0_resolutions: valid_resolutions(Array(doc["phase0_resolutions"]), err: err)
+      }
+    rescue Psych::Exception, StandardError => e
+      err.puts "rulings block: malformed YAML — #{e.message} — dropped (decision-only emission)"
+      {}
+    end
+
+    # ruling is FREE text (the PASS/FAIL/MODIFY/NOT-APPLICABLE convention is
+    # documented, not enforced); only shape is validated here.
+    def self.valid_rulings(entries, err:)
+      entries.filter_map do |entry|
+        unless entry.is_a?(Hash) && entry["ac"].is_a?(String) && !entry["ac"].strip.empty? &&
+               entry["ruling"].is_a?(String) && !entry["ruling"].strip.empty? &&
+               (entry.key?("note") ? entry["note"].is_a?(String) || entry["note"].nil? : true)
+          err.puts "rulings block: dropped invalid ac_rulings entry #{entry.inspect[0, 120]}"
+          next
+        end
+        compact_scalars("ac" => entry["ac"], "ruling" => entry["ruling"], "note" => entry["note"])
+      end
+    end
+
+    def self.valid_resolutions(entries, err:)
+      entries.filter_map do |entry|
+        unless entry.is_a?(Hash) && entry["topic"].is_a?(String) && !entry["topic"].strip.empty? &&
+               (entry.key?("lane") ? entry["lane"].is_a?(String) || entry["lane"].nil? : true) &&
+               (entry.key?("resolution") ? entry["resolution"].is_a?(String) || entry["resolution"].nil? : true)
+          err.puts "rulings block: dropped invalid phase0_resolutions entry #{entry.inspect[0, 120]}"
+          next
+        end
+        compact_scalars("topic" => entry["topic"], "lane" => entry["lane"], "resolution" => entry["resolution"])
+      end
+    end
+  end
+end

data/lib/space_architect/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Architect
-    VERSION = "9.6.0"
+    VERSION = "9.7.0"
   end
 end

data/lib/space_architect.rb

@@ -7,6 +7,7 @@ require_relative "space_architect/harness"
 require_relative "space_architect/routing"
 require_relative "space_architect/gate_lint"
 require_relative "space_architect/gate_evaluator"
+require_relative "space_architect/iteration_emission"
 require_relative "space_architect/architect_project"
 require_relative "space_architect/skill_installer"
 require_relative "space_architect/agent_installer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 9.6.0
+  version: 9.7.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -161,6 +161,7 @@ files:
 - lib/space_architect/gate_evaluator.rb
 - lib/space_architect/gate_lint.rb
 - lib/space_architect/harness.rb
+- lib/space_architect/iteration_emission.rb
 - lib/space_architect/loop_cost.rb
 - lib/space_architect/looplog.rb
 - lib/space_architect/pi/builder-guard.ts