/**
 * Public surface of the `dsh-facet` host row.
 *
 * The augmentation below is the point of this file: `ctx.facetPolicy` is a
 * service published by `provide`, so without it a TypeScript consumer sees the
 * property as missing. The preset half (`dsh-facet/guard`) is typed in
 * `./guard.d.ts`.
 */

import type { Context } from '@deepseek-ai/cordis'
import type z from '@deepseek-ai/schemastery'

/** One session's resolved scope. */
export interface FacetScope {
  /** The session working directory, absolute — also the boundary. */
  readonly cwd: string
  /** The facet root; the session's own folder. */
  readonly root: string
  /** Absolute granted paths outside the root: standing grants, then this session's. */
  readonly extras: string[]
}

/** How an out-of-scope call is handled. */
export type FacetMode = 'ask' | 'deny' | 'off'

/** The deployment's facet policy, published by the host row. */
export interface FacetPolicy {
  readonly mode: FacetMode
  /** System-prompt placement of the invariant rule. */
  readonly sectionOrder: number
  /** Runtime-context placement of the per-session binding. */
  readonly contextOrder: number
  /** Every path always in scope, as configured. */
  readonly standing: string[]
  /** Session ids currently holding a grant. */
  readonly sessions: string[]
  /** The scope of one agent, or `undefined` when it has no working directory. */
  scopeFor(agent: { session?: { id?: unknown; header?: { cwd?: unknown } } } | undefined): FacetScope | undefined
  /** Add paths to one session's grants. */
  grant(sessionId: string, paths: readonly string[], cwd: string): string[]
  /** Drop paths from one session's grants. */
  revoke(sessionId: string, paths: readonly string[], cwd: string): string[]
  /** Clear one session's grants. */
  reset(sessionId: string): string[]
  /** One session's own grants, without the standing ones. */
  grantsFor(sessionId: string): string[]
  /** Drop a finished session's grants. */
  forget(sessionId: string): void
}

declare module '@deepseek-ai/cordis' {
  interface Context {
    /** Published by `dsh-facet`; consumed by `dsh-facet/guard`. */
    facetPolicy: FacetPolicy
  }
}

/** Plugin name. */
export declare const name = 'dsh-facet'

/** Configuration: the deployment's facet policy. */
export interface Config {
  /** How an out-of-scope call is handled. Defaults to `ask`. */
  mode?: FacetMode
  /** Paths always in scope; relative paths resolve against each session's directory. */
  extraRoots?: string[]
  /** Placement of the invariant rule in the system prompt. Defaults to `100`. */
  sectionOrder?: number
  /** Placement of the per-session binding in the runtime-context snapshot. Defaults to `105`. */
  contextOrder?: number
}

export declare const Config: z<Config>

export declare function apply(ctx: Context, config: Config): void