# 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:
  ```csharp
  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

```csharp
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 `docs/implplan/SPRINT_130_scanner_surface.md` once each guild completes its part. If you discover additional shared requirements, extend this guide so future consumers (CLI, Orchestrator) can reuse the flow.