Function Map V1 Contract

Predicate Type (canonical): https://stella.ops/predicates/function-map/v1 Predicate Type (legacy alias): stella.ops/functionMap@v1 DSSE Payload Type: application/vnd.stellaops.function-map.v1+json JSON Schema URI: https://stellaops.org/schemas/function-map-v1.json Schema Version: 1.0.0

Field-naming note: The predicate (subject + predicate payload) serializes with camelCase JSON property names (buildId, expectedPaths, nodeHash, …). The runtime observation record and the verification result serialize with snake_case property names (node_hash, function_name, observation_rate, …). Both conventions are intentional and are preserved below.

Overview

This contract is for engineers generating, signing, or verifying function maps in the Stella Ops reachability pipeline, and for clients of the Platform function-map API and CLI. A function map predicate declares the expected call paths for a service component, enabling verification of runtime behavior (eBPF observations) against static analysis. It serves as the “contract” that runtime observations are verified against, and is typically generated from SBOM + static analysis, then signed for attestation. It follows the in-toto attestation framework.

Ground-truth implementation:

• src/Scanner/__Libraries/StellaOps.Scanner.Reachability/FunctionMap/ (predicate model, generator, claim verifier).
• src/Platform/StellaOps.Platform.WebService/Endpoints/FunctionMapEndpoints.cs (HTTP API).
• src/Cli/StellaOps.Cli/Commands/FunctionMap/FunctionMapCommandGroup.cs (CLI).
• src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/023_runtime_observations.sql (observation persistence).

Predicate Schema

The top-level predicate type field is serialized as _type (not type).

{
  "_type": "https://stella.ops/predicates/function-map/v1",
  "subject": {
    "purl": "pkg:oci/my-service@sha256:abc123...",
    "digest": { "sha256": "abc123..." },
    "name": "my-service"
  },
  "predicate": {
    "schemaVersion": "1.0.0",
    "service": "my-backend",
    "buildId": "build-456",
    "generatedFrom": {
      "sbomRef": "sha256:...",
      "staticAnalysisRef": "sha256:...",
      "binaryAnalysisRef": "sha256:...",
      "hotFunctionPatterns": ["SSL_*", "EVP_*"]
    },
    "expectedPaths": [...],
    "coverage": {
      "minObservationRate": 0.95,
      "windowSeconds": 1800,
      "minObservationCount": null,
      "failOnUnexpected": false
    },
    "generatedAt": "2026-01-23T10:00:00Z",
    "generator": {
      "name": "StellaOps.Scanner.Reachability.FunctionMap",
      "version": "2.0.0",
      "commit": "abc123"
    },
    "metadata": {}
  }
}

Subject

Source: FunctionMapSubject in FunctionMapPredicate.cs.

Predicate Fields

Source: FunctionMapPredicatePayload in FunctionMapPredicate.cs.

Generated From

Source: FunctionMapGeneratedFrom.

Expected Path

Source: ExpectedPath / PathEntrypoint in ExpectedPath.cs. Each expected path represents a call chain starting from an entrypoint:

{
  "pathId": "path-001",
  "description": "TLS handshake via OpenSSL",
  "entrypoint": {
    "symbol": "handleRequest",
    "nodeHash": "sha256:...",
    "purl": "pkg:oci/my-service@sha256:..."
  },
  "expectedCalls": [
    {
      "symbol": "crypto_sign",
      "purl": "pkg:deb/libcrypto3@3.0.0",
      "nodeHash": "sha256:...",
      "probeTypes": ["uprobe"],
      "optional": false,
      "description": "libsodium signing",
      "functionAddress": null,
      "binaryPath": "/usr/lib/libcrypto.so.3"
    }
  ],
  "pathHash": "sha256:...",
  "optional": false,
  "strictOrdering": false,
  "tags": ["crypto"]
}

Path Entrypoint

Expected Call

Source: ExpectedCall in ExpectedCall.cs.

Probe Types

Coverage Thresholds

Source: CoverageThresholds in FunctionMapPredicate.cs.

Node Hash Recipe

Node hashes provide content-addressable identifiers for function calls. The recipe is implemented in FunctionMapGenerator.ComputeNodeHash and intentionally matches PathWitnessBuilder (see Witness V1):

nodeHash = "sha256:" + lowerhex(SHA-256(normalize_purl(PURL) + ":" + normalize_symbol(symbol)))

Where:

• normalize_purl(PURL) = trim() then toLowerInvariant() (lower-cased).
• normalize_symbol(symbol) = trim() only.

The symbol is not demangled, not lower-cased, and leading underscores are not stripped — only surrounding whitespace is trimmed. (An earlier revision of this doc described a demangle/lowercase/strip-underscores recipe that the code does not implement.)

The output digest is hex-encoded lower-case and prefixed with sha256:.

Path Hash Recipe

Source: FunctionMapGenerator.ComputePathHash.

pathHash = "sha256:" + lowerhex(SHA-256(
    join(":", [entrypoint_hex] + sort(call_node_hashes_hex))))

Note the actual algorithm strips the sha256: prefix from each component hash before joining, sorts the call hashes (ordinal) while keeping the entrypoint hash first, and joins with :. The entrypoint hash is always first and is not part of the sort. Sorting is applied regardless of strictOrdering (the generator does not currently vary hashing on strictOrdering).

Coverage Calculation Algorithm

Source: ClaimVerifier.ComputeCoverage. Coverage is computed over expected calls (node hashes), not over whole paths:

for each non-optional path:
  for each non-optional expected_call:
    total_expected_calls += 1
    if observation exists for call.nodeHash:
      observed_calls += 1
      mark path as observed

coverageRate = observed_calls / total_expected_calls
             = 0.0 if total_expected_calls == 0

ComputeCoverage also reports totalPaths, observedPaths (paths with at least one observed call), and unexpectedSymbolCount (distinct observation node hashes not in the expected set).

ComputeCoverage matches purely on nodeHash presence and does not filter by time window or probe type. The full VerifyAsync path (below) applies window and probe-type matching.

Verification Algorithm

Source: ClaimVerifier.VerifyAsync.

VERIFY(functionMap, observations, options):
  1. Resolve effective thresholds (options overrides win over coverage thresholds):
        minObservationRate, windowSeconds, failOnUnexpected
  2. windowEnd   = options.To ?? now
     windowStart = options.From ?? windowEnd - windowSeconds
  3. Filter observations to [windowStart, windowEnd] and, if set,
     to options.ContainerIdFilter / options.PodNameFilter
  4. For each non-optional expected_path:
       For each non-optional expected_call:
         - Look up observations by call.nodeHash
         - If an observation's probeType is in call.probeTypes -> matched (probeTypeMatched=true)
         - If observations exist but probe type differs -> still counted as matched,
           flagged as probe-type mismatch (probeTypeMatched=false)
         - Otherwise -> missing
       path.observed = (no missing calls)
  5. unexpected = observed function names whose nodeHash is in no expected path/call
  6. observationRate = totalMatchedNodeHashes / (totalMatched + totalMissing)
  7. verified = observationRate >= minObservationRate
                AND (NOT failOnUnexpected OR unexpected.count == 0)
  8. Build evidence (functionMapDigest, observationsDigest, observationCount,
     window, verifierVersion) and warnings; return ClaimVerificationResult

Key behaviors that differ from a naive reading:

• The observation rate is call-based (node-hash level), not path-based.
• Optional paths and optional calls are skipped entirely in the rate calculation.
• A call observed with the wrong probe type still counts as observed but raises a warning; it does not by itself fail verification.

Media Types

Source: FunctionMapSchema (DSSE payload type / schema URI), FunctionMapCommandGroup (CLI sign/attest path).

Discrepancy flagged: the canonical DssePayloadType const (application/vnd.stellaops.function-map.v1+json) and the payload type hard-coded in the CLI sign/attest path (application/vnd.stellaops.function-map+json, no .v1) do not match. An earlier revision of this doc listed application/vnd.stella.function-map+json and application/vnd.stella.verification-report+json, neither of which appears in the code base; those have been removed.

Observation Record (NDJSON)

Source: ClaimObservation in Verification/IClaimVerifier.cs. Unlike the predicate, observation fields use snake_case JSON property names. Each line in an offline observations file (CLI --offline --observations) is one such object:

{
  "observation_id": "obs-123",
  "node_hash": "sha256:...",
  "function_name": "crypto_sign",
  "probe_type": "uprobe",
  "observed_at": "2026-01-23T10:05:00Z",
  "observation_count": 42,
  "container_id": "abc123",
  "pod_name": "my-service-pod-xyz",
  "namespace": "production",
  "duration_us": 150
}

The Platform API ObservationDto carries the same snake_case fields except it omits duration_us.

Probe Types

Source: FunctionMapSchema.ProbeTypes.

FunctionMapSchema.ProbeTypes.IsValid validates probe types case-insensitively; the generator validation step rejects any probeTypes value outside this set.

Verification Result

Source: ClaimVerificationResult in Verification/IClaimVerifier.cs. Returned by the claim verifier and by the CLI --format json. Fields use snake_case.

Per-call detail (call_details[], present when IncludeBreakdown is true): symbol, node_hash, observed, observation_count, matched_probe_type, probe_type_matched.

HTTP API (Platform)

Source: src/Platform/StellaOps.Platform.WebService/Endpoints/FunctionMapEndpoints.cs. All routes are mounted under /api/v1/function-maps, require a resolved tenant (RequireTenant()), and are guarded by Platform authorization policies that map to the Platform scopes below.

Scope note: these are Platform-local scopes declared in PlatformScopes.cs (functionmap.read / .write / .verify) and their policies in PlatformPolicies.cs (platform.functionmap.*). They are not present in the canonical Authority scope catalog (StellaOpsScopes.cs); there is no function-map entry there.

Request/response DTOs are defined in src/Platform/StellaOps.Platform.WebService/Contracts/FunctionMapModels.cs and use camelCase property names, except the embedded ObservationDto (snake_case, as noted above). All responses are wrapped in the platform envelope (PlatformItemResponse<T> / PlatformListResponse<T>) carrying tenantId, actorId, dataAsOf, cached, and cacheTtlSeconds.

CLI

Source: src/Cli/StellaOps.Cli/Commands/FunctionMap/FunctionMapCommandGroup.cs. Command group: stella function-map (alias stella fmap).

stella function-map generate

Generates a function_map predicate from an SBOM.

stella function-map verify

Verifies runtime observations against a function_map.

Not yet implemented: online observation query (without --offline) is a stub that emits a warning and verifies against an empty observation set; verify --sign is a stub.

Exit codes (FunctionMapExitCodes)

Persistence

Source: src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/023_runtime_observations.sql. Runtime observations are stored in scanner.runtime_observations and queried via IRuntimeObservationStore (PostgresRuntimeObservationStore).

A composite (node_hash, observed_at DESC) index supports the common lookup pattern. IRuntimeObservationStore exposes store/batch-store, query-by node-hash/container/pod, generic QueryAsync(ObservationQuery), GetSummaryAsync, and PruneOlderThanAsync.