Surface.FS Consumer Integration Guide (Scheduler & Zastava)

Updated: 2025-11-07
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

• 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:Root) 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. Update docs/SCHED-WORKER-16-201-PLANNER.md with the new prefetch flow.

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. Expand observer runbook (docs/modules/zastava/operations/drift.md) with Surface manifest troubleshooting.

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.

Coordinate status updates in the relevant TASKS.md entries and the docs/implplan/SPRINT_13x_scanner_surface.md files (Sprint 130 through 139) once each guild completes its part. If you discover additional shared requirements, extend this guide so future consumers (CLI, Orchestrator) can reuse the flow.