Surface.FS Consumer Integration Guide

Currency note (2026-09-26, commit 942a18727c). The Scheduler service is retired (its scheduling moved to JobEngine; hosts frozen under src/__Obsoleted/JobEngine/) and the Zastava observer/webhook is retired (runtime evidence now comes from RuntimeInstrumentation agents through POST /api/v1/runtime/events). Sections that name Scheduler or Zastava as consumers describe the retired design. The Surface libraries themselves are live under src/Scanner/__Libraries/StellaOps.Scanner.Surface*; Scanner-side paths were checked, deep content was not re-verified.

Updated: 2026-08-22 Audience: Scheduler Worker Guild • Zastava Observer Guild • Surface FS Guild
Depends on: SURFACE-FS-02 (FileSurfaceManifestStore), Surface.Env/Surface.Secrets libraries.

This note captures the minimum wiring required for downstream services now that FileSurfaceManifestStore and the manifest reader/writer abstractions have landed.

1. Shared prerequisites

• Consumers that only deserialize or publish the stellaops.surface.manifest@1 record vocabulary reference StellaOps.Scanner.Surface.Contracts. That producer-owned project is BCL-only and carries no filesystem/cache implementation; its records retain the historical StellaOps.Scanner.Surface.FS namespace and JSON shape.
• Hosts that need the file-backed store/cache reference StellaOps.Scanner.Surface.FS (net10.0) and call:

  services
      .AddSurfaceFileCache()
      .AddSurfaceManifestStore();
  

  This binds Surface:Cache and Surface:Manifest (or SCANNER_SURFACE_* overrides).
• Pull runtime settings via ISurfaceEnvironment to ensure tenants/endpoints line up with Scanner.
• Cache root (Surface:Cache:RootDirectory) must be writable; manifests fall back to <Root>/manifests unless explicitly overridden with Surface:Manifest:RootDirectory.

2. Manifest reader usage

var reader = serviceProvider.GetRequiredService<ISurfaceManifestReader>();
var manifest = await reader.TryGetByUriAsync(surfaceUri, cancellationToken);

• Accept cas://{bucket}/{prefix}/{tenant}/{hh}/{tt}/{digest}.json pointers.
• On cache miss, return null—callers should fall back to existing recompute paths.
• All timestamps are stored in canonical UTC, and metadata dictionaries are alphabetically sorted to keep digests deterministic.

3. Scheduler worker checklist (SCHED-SURFACE-02)

1. Prefetch manifests during planning so reruns can skip redundant layers.
2. Persist {manifestUri, manifestDigest} alongside run plans for traceability.
3. Emit telemetry counters: scheduler_surface_manifest_prefetch_total{result=hit|miss}.
4. Document the prefetch flow in the consumer’s own dossier.

4. Zastava observer checklist (ZASTAVA-SURFACE-02)

1. Resolve manifest pointer from runtime drift events (entrytrace.graph, layer.fragments kinds).
2. Enrich drift diagnostics with manifestDigest and Artifacts[n].metadata.
3. Add failure metric zastava_surface_manifest_failures_total{reason=not_found|fetch_error}.
4. Document Surface manifest troubleshooting in the consumer’s runbook.

5. Testing guidance

• Unit-test manifest prefetch/adoption with local FileSurfaceManifestStore; use temp directories for isolation.
• For integration environments, smoke-test by pointing to the same Surface:Manifest:RootDirectory used by Scanner Worker and verifying pointer fetch before scan jobs execute.

Track consumer work in the owning sprint file under docs/implplan/ (sprint files are the only task ledger). If you discover additional shared requirements, extend this guide so future consumers (CLI, Orchestrator) can reuse the flow.