Add Authority Advisory AI and API Lifecycle Configuration

- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings.
- Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations.
- Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration.
- Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options.
- Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations.
- Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client.
- Updated project file to include necessary package references for the new Issuer Directory Client library.

docs/modules/scanner/design/surface-fs.md

@@ -73,7 +73,8 @@ Surface.FS library for .NET hosts provides:
 - `ISurfaceManifestWriter` / `ISurfaceManifestReader` interfaces.
 - Content-addressed path builder (`SurfacePathBuilder`).
 - Tenant namespace isolation and bucket configuration (via Surface.Env).
-- Local cache management (using `SCANNER_SURFACE_CACHE_ROOT` and quota).
+- Local cache abstraction `ISurfaceCache` with default `FileSurfaceCache` implementation (uses `Surface:Cache:Root` / `SCANNER_SURFACE_CACHE_ROOT`, enforces quotas, serialises writes with per-key semaphores).
+- `SurfaceCacheKey` helper that normalises cache entries as `{namespace}/{tenant}/{sha256}`. EntryTrace graphs use the `entrytrace.graph` namespace so Worker/WebService/CLI can share cached results deterministically.
 - Metrics: `surface_manifest_put_seconds`, `surface_manifest_cache_hit_total`, etc.
 
 ## 5. Retention & Eviction
@@ -97,6 +98,10 @@ offline/surface/
 
 Import script calls `PutManifest` for each manifest, verifying digests. This enables Zastava and Scheduler running offline to consume cached data without re-scanning.
 
+### 6.1 EntryTrace Cache Usage
+
+Scanner.Worker serialises EntryTrace graphs into Surface.FS using `SurfaceCacheKey(namespace: "entrytrace.graph", tenant, sha256(options|env|entrypoint))`. At runtime the worker checks the cache before invoking analyzers; cache hits bypass parsing and feed the result store/attestor pipeline directly. The same namespace is consumed by WebService and CLI to retrieve cached graphs for reporting.
+
 ## 7. Security & Tenancy
 
 - Tenant ID is mandatory; Surface.Validation enforces match with Authority token.

docs/modules/scanner/design/surface-secrets.md

@@ -52,7 +52,18 @@ public sealed record SurfaceSecretRequest
 
 ### 3.2 Secret Handle
 
-`SurfaceSecretHandle` exposes typed accessors (`AsCredentials()`, `AsTlsCertificate()`) and ensures sensitive data is cleared when disposed.
+`SurfaceSecretHandle` exposes typed accessors (`AsBytes()`, `AsCredentials()`, `AsTlsCertificate()`) and ensures sensitive data is cleared when disposed. Consumers that expect string material attempt UTF-8 decoding first and, if decoding fails, fall back to returning a base64 representation rather than dropping binary content.
+
+### 3.3 Environment & Config References
+
+Runtime configuration can reference secrets using the URI scheme `secret://{secretType}/{name?}`. Example:
+
+```
+SCANNER_ENTRYTRACE_ENV__0=API_TOKEN=secret://registry/primary
+SCANNER_ENTRYTRACE_ENV__1=TLS_CERT=secret://tls/edge-gateway
+```
+
+During scan execution, Scanner.Worker resolves each placeholder via `ISurfaceSecretProvider` before invoking analyzers, replacing the environment variable with the resolved value (base64 when non-text). Missing secrets raise `SurfaceSecretNotFoundException` and are surfaced as warnings without hard-failing the scan.
 
 ## 4. Configuration
 

docs/modules/scanner/design/surface-validation.md

@@ -13,32 +13,36 @@ Surface.Validation provides a shared validator framework to ensure all surface c
 ```csharp
 public interface ISurfaceValidator
 {
-    ValueTask<ValidationResult> ValidateAsync(SurfaceValidationContext context, CancellationToken ct = default);
+    ValueTask<SurfaceValidationResult> ValidateAsync(SurfaceValidationContext context, CancellationToken ct = default);
 }
 
-public sealed record SurfaceValidationContext
-(
-    SurfaceEnvironmentSettings Environment,
+public sealed record SurfaceValidationContext(
     IServiceProvider Services,
-    string ComponentName
-);
+    string ComponentName,
+    SurfaceEnvironmentSettings Environment,
+    IReadOnlyDictionary<string, object?> Properties)
+{
+    public static SurfaceValidationContext Create(
+        IServiceProvider services,
+        string componentName,
+        SurfaceEnvironmentSettings environment,
+        IReadOnlyDictionary<string, object?>? properties = null);
+}
 
-public sealed record ValidationResult
-(
-    bool IsSuccess,
-    IReadOnlyCollection<SurfaceValidationIssue> Issues
-);
+public interface ISurfaceValidatorRunner
+{
+    ValueTask<SurfaceValidationResult> RunAllAsync(SurfaceValidationContext context, CancellationToken ct = default);
+    ValueTask EnsureAsync(SurfaceValidationContext context, CancellationToken ct = default);
+}
 
-public sealed record SurfaceValidationIssue
-(
+public sealed record SurfaceValidationIssue(
     string Code,
     string Message,
     SurfaceValidationSeverity Severity,
-    string? Hint = null
-);
+    string? Hint = null);
 ```
 
-Validators register with DI (`services.AddSurfaceValidation()`). Hosts call `ISurfaceValidatorRunner.RunAllAsync()` during startup and periodically (optional) to re-check configuration.
+`Properties` carries optional context-specific metadata (e.g., `jobId`, `imageDigest`, cache paths) so validators can tailor diagnostics without pulling additional services. Validators register with DI (`services.AddSurfaceValidation()`). Hosts call `ISurfaceValidatorRunner.RunAllAsync()` during startup and before workload execution to capture misconfiguration early; `EnsureAsync()` rethrows when `Surface:Validation:ThrowOnFailure=true`.
 
 ## 3. Built-in Validators
 
@@ -76,6 +80,7 @@ Validators can access DI services (e.g., HttpClient, Authority token provider) t
 ## 6. Integration Guidelines
 
 - **Scanner Worker/WebService**: fail startup if any error-level issue occurs; log warnings but continue running.
+- **Scanner EntryTrace**: execute `RunAllAsync` for each scan job with properties `{imageDigest, jobId, configPath, rootPath}`. If the result contains errors, skip analysis and log the issue summary instead of failing the entire scan.
 - **Zastava Webhook**: treat validation errors as fatal (webhook should not enforce policies when surface preconditions fail). Display validation error summary in `/readyz` response to aid debugging.
 - **Analysers**: call `SurfaceValidation.Ensure()` before executing heavy work to catch misconfiguration during integration tests.