/**
 * Muscle memory for tool outputs — the persistence half of runtime shape
 * inference (see shape-inference.ts for the algorithm).
 *
 * Observed shapes live in the already-migrated `plugin_storage` table under a
 * reserved system plugin id: owner-scoped, tenant-partitioned, and untouched
 * by tool-catalog refresh (which deletes and recreates `tool` rows, so the
 * tool row itself is not a viable home). An in-memory read-through cache
 * keeps the hot path off the database: within one executor instance a tool's
 * shape is loaded at most once, and a write happens only when a new
 * observation actually changes the merged shape — after a few calls a stable
 * API stops producing writes entirely.
 *
 * `observe` never fails and is intended to be forked off the dispatch path;
 * `recall` degrades to "no memory" on any storage failure.
 */

import { Clock, Effect } from "effect";

import type { Owner } from "./ids";
import type { PluginStorageFacade } from "./plugin-storage";
import { observeShape, type ObservedShape } from "./shape-inference";

/** Reserved system namespace inside `plugin_storage`; not a real plugin. */
export const SHAPE_MEMORY_PLUGIN_ID = "executor.shape-memory";
const COLLECTION = "observed-output-shapes";

export type ShapeMemory = {
  /**
   * Fold one successful tool payload into the tool's remembered shape.
   * Structure only — values never leave this call. Never fails.
   */
  readonly observe: (address: string, owner: Owner, value: unknown) => Effect.Effect<void>;
  /** The remembered shape for an address, or null when nothing is known. */
  readonly recall: (address: string, owner: Owner) => Effect.Effect<ObservedShape | null>;
};

export const makeShapeMemory = (storage: PluginStorageFacade): ShapeMemory => {
  const cache = new Map<string, ObservedShape | null>();
  const persisted = new Map<string, string>();

  const cacheKey = (owner: Owner, address: string) => `${owner}:${address}`;

  const load = (address: string, owner: Owner): Effect.Effect<ObservedShape | null> =>
    Effect.gen(function* () {
      const key = cacheKey(owner, address);
      const hit = cache.get(key);
      if (hit !== undefined) return hit;
      const entry = yield* storage
        .getForOwner<ObservedShape>({ owner, collection: COLLECTION, key: address })
        .pipe(Effect.catch(() => Effect.succeed(null)));
      const record = entry?.data ?? null;
      cache.set(key, record);
      if (record !== null) persisted.set(key, JSON.stringify(record.schema));
      return record;
    });

  const observe = (address: string, owner: Owner, value: unknown): Effect.Effect<void> =>
    Effect.gen(function* () {
      const key = cacheKey(owner, address);
      const prior = yield* load(address, owner);
      const now = yield* Clock.currentTimeMillis;
      const next = observeShape(prior, value, now);
      cache.set(key, next);
      // Write only when the merged shape actually changed — observation
      // counters alone are bookkeeping, not worth a row write per call.
      const schemaJson = JSON.stringify(next.schema);
      if (persisted.get(key) === schemaJson) return;
      yield* storage
        .put({ owner, collection: COLLECTION, key: address, data: next })
        .pipe(Effect.catch(() => Effect.succeed(null)));
      persisted.set(key, schemaJson);
    }).pipe(Effect.catchCause(() => Effect.void));

  return {
    observe,
    recall: (address, owner) =>
      load(address, owner).pipe(Effect.catchCause(() => Effect.succeed(null))),
  };
};

/**
 * Render a remembered shape as the JSON Schema served in place of a missing
 * declared output schema. The description marks provenance so a reader (and
 * the schema view) can tell an observed shape from an author-declared one.
 */
export const observedShapeToJsonSchema = (record: ObservedShape): unknown => ({
  ...record.schema,
  description: `Observed from ${record.observations} live response${record.observations === 1 ? "" : "s"}; fields may be incomplete.`,
});