import type { MemoModelDTO, MemoRelationship } from '../model/semantic.js';
import type { RelationshipCreateRequest, RelationshipDefinitionDTO, RelationshipUpdateRequest } from '../model/relationship-legality.js';
import { type IrIdentityIndex } from '../model/ir-identity.js';
import { type RelationshipNotation } from './sysml-notation.js';
/** Default file used when the project has no better home for a relationship. */
export declare const CANONICAL_RELATIONSHIP_FILE = "model/catalog/relationships.sysml";
/** Directory segments holding view/presentation SysML — never a relationship home. */
export declare const DEFAULT_PRESENTATION_DIRS: string[];
/** Filenames a package uses to collect its relationships. */
export declare const DEFAULT_RELATIONSHIP_FILE_PATTERN: RegExp;
export interface RelationshipWriterOptions {
    /** Absolute project root. Nothing outside it is ever written. */
    projectRoot: string;
    /**
     * Per-package designated relationship files, project-relative.
     * Keyed by package qualified name, from project configuration.
     */
    designatedFiles?: Record<string, string>;
    /** Configured canonical relationship file, project-relative. */
    canonicalFile?: string;
    /**
     * Absolute roots of installed ontology/library packages. Files under these
     * are read-only content and are never modified.
     */
    ontologyRoots?: string[];
    /**
     * Directory segments that hold view/presentation SysML. A relationship is a
     * model fact and is never written into one.
     */
    presentationDirs?: string[];
    /** Filenames treated as a package's relationship collection. */
    relationshipFilePattern?: RegExp;
    /**
     * Identity index of the current revision.
     *
     * Present whenever a compiled revision exists. Absent only before the first
     * successful lowering, and a request quoting an identity is then refused
     * rather than written blind.
     */
    irIndex?: IrIdentityIndex;
}
/** Why a particular file was chosen, for logging and for the UI to show. */
export type PlacementReason = 'requested' | 'designated-package-file' | 'common-package-file' | 'source-element-file' | 'canonical-file' | 'canonical-file-created';
export interface RelationshipPlacement {
    /** Project-relative .sysml path that will own the relationship. */
    file: string;
    reason: PlacementReason;
    /** True when the file does not exist yet and will be created. */
    willCreate: boolean;
}
export interface RelationshipWriteResult {
    success: boolean;
    /** Project-relative file actually written. */
    sourceFile?: string;
    /**
     * Stable ID (the connection usage name) of the created relationship.
     *
     * Absent for notations SysML does not name — see `notation`.
     */
    relationshipId?: string;
    /** SysML production the relationship was written in. */
    notation?: RelationshipNotation;
    /** The exact declaration text inserted. */
    declaration?: string;
    placementReason?: PlacementReason;
    error?: string;
    /** Set when the failure was a stale endpoint identity. */
    stale?: boolean;
}
export interface RelationshipRemoveResult {
    success: boolean;
    sourceFile?: string;
    /** The declaration removed, so the caller can offer an exact undo. */
    removedDeclaration?: string;
    error?: string;
}
export interface RelationshipUpdateResult {
    success: boolean;
    sourceFile?: string;
    declaration?: string;
    error?: string;
}
/**
 * Whether a project-relative path is a legal home for a model relationship.
 *
 * Rejects anything outside the project, non-.sysml files, installed ontology
 * content, and the diagram presentation section. Symlinks are resolved before
 * the containment check so an in-tree link cannot escape the project.
 */
export declare function isWritableRelationshipFile(relativePath: string, options: RelationshipWriterOptions): boolean;
/**
 * Choose the file that will own a new relationship, deterministically:
 *
 *   1. the file the request explicitly asked for
 *   2. the designated relationship file of the active model package
 *   3. an existing relationships file in the nearest common package of both
 *      endpoints, else the source element's own file within that package
 *   4. the configured canonical relationship file, when it already exists
 *   5. the canonical file, created only because nothing above was suitable
 *
 * Every candidate passes isWritableRelationshipFile before it is considered.
 */
export declare function resolveRelationshipPlacement(request: Pick<RelationshipCreateRequest, 'sourceId' | 'targetId' | 'owningFile'>, model: Pick<MemoModelDTO, 'elements'>, options: RelationshipWriterOptions): RelationshipPlacement;
/**
 * A stable, explicit relationship ID. Named connection usages are what make a
 * relationship addressable for inspection, deletion, and deep links, so every
 * authored relationship gets one.
 */
export declare function generateRelationshipId(type: string, sourceId: string, targetId: string, taken: Iterable<string>): string;
/**
 * Render a relationship as SysML source.
 *
 * The form comes from the language, not from this module — see
 * `./sysml-notation.ts`. Kept as a named export because the shape "id,
 * definition, endpoints" is what every caller has.
 */
export declare function generateRelationshipDeclaration(id: string, definition: RelationshipDefinitionDTO, sourceId: string, targetId: string, flowItem?: string, guard?: string): string;
/**
 * Write a relationship into project SysML.
 *
 * The declaration is inserted inside the target package by source offset, the
 * whole updated file is reparsed, and the write is abandoned if the result does
 * not parse or does not contain the new connection.
 */
export declare function writeRelationship(request: RelationshipCreateRequest, definition: RelationshipDefinitionDTO, model: Pick<MemoModelDTO, 'elements' | 'relationships'>, options: RelationshipWriterOptions): Promise<RelationshipWriteResult>;
/**
 * Atomically replace one relationship declaration at the exact range supplied
 * by the current compiled model. This also supports anonymous SysML `flow` and
 * `succession` usages, which deliberately have no stable declared name.
 */
export declare function updateRelationship(request: RelationshipUpdateRequest, relationship: MemoRelationship, definition: RelationshipDefinitionDTO, model: Pick<MemoModelDTO, 'elements'>, options: RelationshipWriterOptions): Promise<RelationshipUpdateResult>;
/**
 * Remove exactly one connection usage from its owning file.
 *
 * Only the declaration's own source range is cut — together with the whitespace
 * on its line — so neighbouring comments and declarations are preserved. Both
 * endpoint elements are left completely untouched.
 */
export declare function removeRelationship(relationship: Pick<MemoRelationship, 'id' | 'file' | 'named'>, options: RelationshipWriterOptions): Promise<RelationshipRemoveResult>;
//# sourceMappingURL=relationship-writer.d.ts.map